Install & Compatibility
Where this runs
tested against v0.33.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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 68.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.000s · 69MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LeafletWidget
✓ from leaflet import LeafletWidget
✗ from leaflet import LeafletWidget
Add 'leaflet' to INSTALLED_APPS, configure LEAFLET_CONFIG, then use LeafletGeoAdmin for your GIS model admin.
INSTALLED_APPS = [
'leaflet',
'django.contrib.gis',
# ...
]
LEAFLET_CONFIG = {
'DEFAULT_CENTER': (51.5, -0.09),
'DEFAULT_ZOOM': 5,
'MIN_ZOOM': 3,
'MAX_ZOOM': 18,
}
# In your admin.py:
from leaflet.admin import LeafletGeoAdmin
from django.contrib.gis import admin
class LocationAdmin(LeafletGeoAdmin):
pass
admin.site.register(Location, LocationAdmin)
Debug
Known issues
breakingdjango-leaflet dropped support for Django <3.2 in version 0.29.0. If upgrading from an older version, ensure Django >=3.2 or pin to 0.28.x.fixUpdate Django to 3.2+ or use django-leaflet==0.28.2.
affects: >=0.29.0
breakingLeaflet 1.0+ changed tile layer URLs; default OSM tile URL changed from http to https. If you override tiles via LEAFLET_CONFIG, ensure you use protocol-relative or https URLs.fixUpdate your LEAFLET_CONFIG tiles to 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'. affects: >=0.30.0 (Leaflet 1.7+)
gotchaLeafletWidget displays a map but does not handle form submission validation for geometry fields. You must use a GeoDjango form field (e.g., PointField, PolygonField) in your form; LeafletWidget is just the rendering widget.fixUse forms.PointField(widget=LeafletWidget()) in your form or model form.
affects: all
deprecatedThe 'leaflet.extras' module (ExtraAdminMixin, etc.) is deprecated in favor of directly using LeafletGeoAdmin or custom admin. It may be removed in a future release.fixReplace 'from leaflet.extras import LeafletGeoAdmin' with 'from leaflet.admin import LeafletGeoAdmin'.
affects: >=0.30.0
Upgrade
Version history
0.33.0latest on PyPI · released Dec 1, 2025
Audit
Dependencies
djangorequiredRequired: Django map widget