Installation¶
leafmap supports Python 3.9 and later. The core package is lightweight; heavier features (raster tiling, vector analysis, extra mapping backends) are available through optional dependencies.
Install from PyPI¶
leafmap is available on PyPI. To install leafmap, run this command in your terminal:
1 | |
Install from conda-forge¶
leafmap is also available on conda-forge. If you have Miniforge (recommended), Miniconda or Anaconda installed on your computer, you can install leafmap using the following command:
1 | |
Some optional dependencies (e.g., geopandas and localtileserver) depend on compiled libraries such as GDAL, which can be challenging to install with pip on some computers, especially Windows. It is highly recommended that you create a fresh conda environment for them:
1 2 | |
Miniforge ships with mamba, a faster drop-in replacement for conda. If you have it, you can replace conda with mamba in the commands above.
Optional dependencies¶
Leafmap has various optional dependencies to enable additional features. You can install them as needed:
| Extra | Command | Enables |
|---|---|---|
raster |
pip install "leafmap[raster]" |
Local raster/COG visualization (localtileserver, rioxarray, TiTiler, NetCDF) |
vector |
pip install "leafmap[vector]" |
Vector analysis, OpenStreetMap (osmnx), PMTiles, lonboard, classification |
maplibre |
pip install "leafmap[maplibre]" |
The MapLibre GL backend (leafmap.maplibregl) |
backends |
pip install "leafmap[backends]" |
The bokeh, kepler.gl, MapLibre, pydeck and plotly backends |
polars |
pip install "leafmap[polars]" |
add_polars() for Polars DataFrames with geometry columns |
duckdb |
pip install "leafmap[duckdb]" |
DuckDB and SQL integration |
sql |
pip install "leafmap[sql]" |
Reading vector data from PostGIS |
pmtiles |
pip install "leafmap[pmtiles]" |
Creating and serving PMTiles |
titiler |
pip install "leafmap[titiler]" |
Running a local TiTiler server |
usgs |
pip install "leafmap[usgs]" |
USGS hydrography and 3DEP elevation data |
lidar |
pip install "leafmap[lidar]" |
LiDAR point cloud visualization |
apps |
pip install "leafmap[apps]" |
Building web apps with Streamlit, VoilĂ and Solara |
ai |
pip install "leafmap[ai]" |
AI/ML features (torchgeo, raster-vision) |
Multiple extras can be combined, for example pip install "leafmap[raster,vector,maplibre]".
Install from GitHub¶
To install the development version from GitHub using Git, run the following command in your terminal:
1 | |
Use docker¶
You can also use docker to run leafmap:
1 | |
Upgrade leafmap¶
If you have installed leafmap before and want to upgrade to the latest version, you can run the following command in your terminal:
1 | |
If you use conda, you can update leafmap to the latest version by running the following command in your terminal:
1 | |
To install the development version from GitHub directly within Jupyter notebook without using Git, run the following code:
1 2 | |
Check your installation¶
To print the versions of leafmap and its key dependencies (useful when reporting an issue), run:
1 2 | |
Troubleshooting¶
If the interactive map does not show up in Jupyter Notebook or JupyterLab, or you see an error such as Error displaying widget: model not found, the Jupyter widget front-end is usually out of sync with the Python packages. Modern versions of JupyterLab (4.x) and Notebook (7.x) install widget extensions automatically together with the Python package, so no jupyter nbextension or jupyter labextension install commands are needed.
Try the following steps:
-
Make sure
ipywidgets,ipyleafletand Jupyter are installed in the same environment as the kernel you are using, and upgrade them together:1pip install -U ipywidgets ipyleaflet jupyterlab notebook -
Restart the Jupyter server (not just the kernel) and hard-refresh the browser page.
- Run
jupyter labextension listand check thatjupyter-leafletand@jupyter-widgets/jupyterlab-managerare listed as enabled.
If the issue persists, you can open an issue on the ipyleaflet repository, or try a different backend such as import leafmap.foliumap as leafmap or import leafmap.maplibregl as leafmap.
Alternatively, you can run leafmap directly in the cloud without installing anything: