Install & Compatibility
Where this runs
tested against v0.20.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 2.256s · 88.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.7s · import 2.005s · 89MB
81MB installed
● package 81MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Map
✓ from ipyleaflet import Map
Marker
✓ from ipyleaflet import Marker
TileLayer
✓ from ipyleaflet import TileLayer
basemaps
✓ from ipyleaflet import basemaps
DrawControl
✓ from ipyleaflet import DrawControl
FullScreenControl
✓ from ipyleaflet import FullScreenControl
jupyter_leaflet
✓ from ipyleaflet import Map
✗ import jupyter_leaflet
jupyter-leaflet is the npm package (frontend component), not the Python package to import.
This quickstart demonstrates how to create a basic interactive map and add a draggable marker using ipyleaflet within a Jupyter environment.
from ipyleaflet import Map, Marker
# Create a map centered at a specific location
m = Map(center=(52.204793, 0.121558), zoom=10)
# Add a marker
marker = Marker(location=(52.204793, 0.121558), draggable=True)
m.add_layer(marker)
# Display the map (in Jupyter environment)
m
Debug
Known issues
breakingOlder versions of ipyleaflet (pre-0.18.0) experienced issues with JupyterLab 4.x, where map attributes like zoom or center would not update. This was addressed in version 0.18.0.fixUpgrade ipyleaflet to version 0.18.0 or newer: `pip install --upgrade ipyleaflet`.
affects: <0.18.0
deprecatedThe `add_control()` and `add_layer()` methods on the Map object were deprecated in version 0.17.0. Users should now use the more general `add()` method.fixReplace `map.add_layer(layer)` with `map.add(layer)` and `map.add_control(control)` with `map.add(control)`.
affects: >=0.17.0
gotchaFor older Jupyter Notebook versions (prior to 5.3) or JupyterLab <=2, manual installation of the Jupyter extension might be required. Failure to do so can result in widgets not displaying.fixFor Jupyter Notebook, run `jupyter nbextension enable --py --sys-prefix ipyleaflet`. For JupyterLab <=2, run `jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-leaflet`.
affects: <0.19.2 (for nbextension note), <=2 (for JupyterLab)
gotchaThe default zoom level for a newly created `Map()` object changed from 12 to 4 in version 0.20.0, potentially affecting existing code or expectations for initial map views.fixExplicitly set the `zoom` parameter when initializing `Map()` if a specific initial zoom level is desired, e.g., `m = Map(zoom=12)`.
affects: >=0.20.0
gotchaipyleaflet does not currently work in Google Colab due to limitations with ipywidgets integration in that environment, and maps will not display.fixUse a local Jupyter environment (Jupyter Notebook, JupyterLab) or a service like Binder instead of Google Colab for ipyleaflet. Libraries like `leafmap` automatically switch to `folium` in Colab.
affects: All
Errors
Common errors & fixes
Error displaying widget: model not found
The ipyleaflet Jupyter extension is not properly installed or enabled, preventing the frontend from rendering the widget. This is a common issue.
fixEnsure `ipyleaflet` is installed correctly. For Jupyter Notebook, try `jupyter nbextension enable --py --sys-prefix ipyleaflet`. For JupyterLab, try `jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-leaflet` (for older versions of Lab).
Map attributes (e.g., zoom, center) do not update in JupyterLab.
This issue was prevalent in ipyleaflet versions prior to 0.18.0 when used with JupyterLab 4.x due to compatibility problems.
fixUpgrade ipyleaflet to version 0.18.0 or newer: `pip install --upgrade ipyleaflet`.
Map does not display anything, no error message, just empty output.
This can happen if the widget state isn't correctly saved or the kernel is no longer available. Often points to an underlying installation or environment issue, or running in an unsupported environment like Google Colab.
fixRestart the Jupyter kernel. Verify the extension is enabled (see 'Error displaying widget' fix). Confirm you are not running in Google Colab. If using an older JupyterLab, ensure the labextension is installed.
Upgrade
Version history
0.20.0latest on PyPI · released Jun 13, 2025
Audit
Dependencies
ipywidgetsrequiredipyleaflet is built upon ipywidgets for interactive functionality in Jupyter environments.
PythonrequiredRequires Python 3.8 or higher.