ipyleaflet

Common errors

• Error displaying widget: model not found

  cause The ipyleaflet Jupyter extension is not properly installed or enabled, preventing the frontend from rendering the widget. This is a common issue.
  fix Ensure `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.

  cause This issue was prevalent in ipyleaflet versions prior to 0.18.0 when used with JupyterLab 4.x due to compatibility problems.
  fix Upgrade ipyleaflet to version 0.18.0 or newer: `pip install --upgrade ipyleaflet`.

• Map does not display anything, no error message, just empty output.

  cause 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.
  fix Restart 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.

Warnings

• breaking Older 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.
  Fix: Upgrade ipyleaflet to version 0.18.0 or newer: `pip install --upgrade ipyleaflet`.
• deprecated The `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.
  Fix: Replace `map.add_layer(layer)` with `map.add(layer)` and `map.add_control(control)` with `map.add(control)`.
• gotcha For 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.
  Fix: For Jupyter Notebook, run `jupyter nbextension enable --py --sys-prefix ipyleaflet`. For JupyterLab <=2, run `jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-leaflet`.
• gotcha The 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.
  Fix: Explicitly set the `zoom` parameter when initializing `Map()` if a specific initial zoom level is desired, e.g., `m = Map(zoom=12)`.
• gotcha ipyleaflet does not currently work in Google Colab due to limitations with ipywidgets integration in that environment, and maps will not display.
  Fix: Use 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.

Install

• pip install ipyleaflet Basic Installation
• jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-leaflet JupyterLab Extension (for JupyterLab <=2)

Imports

• 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
  wrong:

  import jupyter_leaflet

  correct:

  from ipyleaflet import Map

  jupyter-leaflet is the npm package (frontend component), not the Python package to import.

Quickstart

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