FAQ¶
How do I report an issue or make a feature request¶
Please go to https://github.com/opengeos/leafmap/issues. When reporting a bug, include a minimal code example and the output of the following code so that the versions of leafmap and its dependencies are known:
1 2 | |
What's the difference between folium and ipyleaflet¶
A key difference between ipyleaflet and folium is that ipyleaflet is built upon ipywidgets and allows bidirectional communication between the front-end and the Python kernel, so the map can capture user input (e.g., mouse clicks and drawn shapes). Folium produces static HTML maps and is meant for displaying data only (source). As a result, the leafmap toolbar and interactive tools are only available with the ipyleaflet backend, while folium maps are easy to save as standalone HTML files and embed in web apps.
How to use a specific plotting backend¶
import leafmap uses the ipyleaflet plotting backend by default, in Jupyter Notebook, JupyterLab, Google Colab and VS Code. In marimo notebooks, it uses the folium backend. To use a specific plotting backend, import its module explicitly:
import leafmap.leafmap as leafmap(ipyleaflet)import leafmap.foliumap as leafmap(folium)import leafmap.maplibregl as leafmap(MapLibre GL JS)import leafmap.deckgl as leafmap(lonboard)import leafmap.deck as leafmap(pydeck)import leafmap.kepler as leafmap(kepler.gl)import leafmap.plotlymap as leafmap(plotly)import leafmap.bokehmap as leafmap(bokeh)
Note that the backends do not offer equal functionality. See Get Started for a comparison.
Why the interactive map does not show up¶
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, so the old jupyter nbextension and jupyter labextension install commands are no longer 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 enabled.
If the issue persists, you can open an issue on the ipyleaflet repository, or try another backend such as import leafmap.foliumap as leafmap.
Alternatively, you can run leafmap directly in the cloud using Google Colab or Binder.
Why is the map center different between backends¶
The ipyleaflet, folium, plotly, kepler.gl and lonboard (deckgl) backends use (latitude, longitude) order for center, following the Leaflet convention. The MapLibre (maplibregl) backend uses (longitude, latitude), following the MapLibre GL JS and GeoJSON convention. For example, the same view of the contiguous United States is leafmap.Map(center=(40, -100)) with ipyleaflet and leafmap.Map(center=(-100, 40)) with MapLibre.
How do I save a map as an HTML file¶
Most backends provide a to_html() method:
1 2 | |
How do I set API keys¶
Some basemaps and data sources require API keys, such as MAPTILER_KEY for MapTiler styles in the MapLibre backend or GOOGLE_MAPS_API_KEY for Google basemaps. Set them as environment variables before importing leafmap, since some keys (e.g., GOOGLE_MAPS_API_KEY) are read when the package is imported:
1 2 3 4 | |
In Google Colab, you can also store keys in the Colab Secrets panel. For keys looked up when a function is called (such as MAPTILER_KEY), leafmap checks Colab Secrets first and falls back to the environment variable. Google basemaps are the exception: GOOGLE_MAPS_API_KEY is only read from the environment when leafmap is imported, so copy it from Secrets into the environment first:
1 2 3 4 5 6 | |
How to use leafmap in countries where Google Services are blocked¶
If you are trying to use leafmap in countries where Google Services are blocked (e.g., China), you will need a VPN. Use leafmap.set_proxy(port=your-port-number) to connect to Google servers. Otherwise, you might encounter a connection timeout issue.
1 2 3 4 | |