Install & Compatibility
Where this runs
tested against v1.0.15 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.928s · 129.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.1s · import 0.824s · 130MB
154MB installed
● package 154MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dl
✓ import dash_leaflet as dl
✗ import dash_leaflet
Functions as dl.Map, dl.TileLayer, etc. Using dash_leaflet.Map fails.
Map
✓ dl.Map(children=[...], center=[lat, lng], zoom=10, style={'height': '500px'})
✗ dl.Map(children=[...], center=dict(lat=..., lng=...), zoom=10)
center must be a list [lat, lng], not a dict.
Creates a simple Dash app with a Leaflet map centered on London, including a tile layer and a marker with a popup.
import dash
from dash import html
import dash_leaflet as dl
app = dash.Dash(__name__)
app.layout = html.Div([
dl.Map(center=[51.505, -0.09], zoom=13, children=[
dl.TileLayer(),
dl.Marker(position=[51.505, -0.09], children=[
dl.Popup('Hello London')
])
], style={'width': '100%', 'height': '50vh'}, id='map')
])
if __name__ == '__main__':
app.run_server(debug=True)
Debug
Known issues
breakingVersion 1.0.0+ changed from 'children' prop to nested children for Map and other components. Old syntax using 'children' as a prop no longer works.fixReplace dl.Map(children=[...]) with dl.Map([...]) or use children keyword but ensure it's a list of components.
affects: <1.0.0 -> >=1.0.0
gotchaThe center prop for Map must be a list of two floats [lat, lng], not a tuple or dict. Many users mistakenly pass a dict like {'lat': 51.5, 'lng': -0.09}.fixUse center=[51.5, -0.09]
affects: all
deprecatedThe 'children' prop in dl.Marker, dl.Polyline, etc. is deprecated in favor of placing popups/tooltips as children directly. Using children=dl.Popup(...) still works but may be removed in future.fixPlace dl.Popup as a child element: dl.Marker(position=[...], children=[dl.Popup('text')]) affects: >=1.0.0
gotchaGeoJSON data must be a dictionary (GeoJSON FeatureCollection), not a JSON string or file path. Common mistake: loading with json.loads and passing the string directly.fixUse: import json; with open('data.geojson') as f: data = json.load(f); dl.GeoJSON(data=data) affects: all
gotchaThe 'style' prop on Map must be a valid CSS object (dictionary), not a string. Missing style may cause the map to not render (height defaults to 0).fixSet style={'width': '100%', 'height': '500px'} on the Map component. affects: all
Errors
Common errors & fixes
ImportError: cannot import name 'Map' from 'dash_leaflet'
Using `from dash_leaflet import Map` instead of importing the module and using dl.Map.
fixUse `import dash_leaflet as dl` then `dl.Map(...)`.
AttributeError: module 'dash_leaflet' has no attribute 'Map'
Older version of dash-leaflet (<1.0) or incorrect import. Also if using `import dash_leaflet` without alias.
fixUpgrade: pip install --upgrade dash-leaflet, and always use `import dash_leaflet as dl`.
TypeError: 'NoneType' object is not iterable
Passing `center` as None or forgetting to set it. Map requires center and zoom.
fixAlways provide center=[lat, lng] and zoom=int.
dash.exceptions.InvalidCallbackReturnValue: The callback ... returned a value of type ... which is not JSON serializable.
Returning a Python dict or object that is not JSON-serializable in a callback's output that expects a component property (e.g., center, zoom).
fixEnsure callback returns plain lists/dicts (JSON-compatible) for map properties.
Leaflet map not visible (blank white area)
Missing `style` prop on Map component; default height is 0.
fixAdd `style={'width': '100%', 'height': '500px'}` to the Map component. Upgrade
Version history
1.1.3latest on PyPI · released May 15, 2025
Audit
Dependencies
dashrequiredRequired to run Dash apps; dash-leaflet depends on dash >=2.0.