django-leaflet

0.33.0 verified Mon Apr 27 auth: no python

django-leaflet provides a Django map widget for displaying and editing OpenStreetMap / Leaflet maps in admin and front-end forms. Version 0.33.0 supports Python >=3.10, Leaflet 1.7+. Release cadence: occasional, with last release in 2024.

pip install django-leaflet

Common errors

error ImportError: cannot import name 'LeafletWidget' from 'leaflet' ↓

cause Incorrect import path; LeafletWidget is in leaflet.forms.widgets, not top-level leaflet.

fix

Use: from leaflet.forms.widgets import LeafletWidget

error django.core.exceptions.ImproperlyConfigured: 'django.contrib.gis' is not in INSTALLED_APPS ↓

cause django-leaflet requires django.contrib.gis to be installed.

fix

Add 'django.contrib.gis' to INSTALLED_APPS in your Django settings.

Warnings

breaking django-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. ↓

fix Update Django to 3.2+ or use django-leaflet==0.28.2.

breaking Leaflet 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. ↓

fix Update your LEAFLET_CONFIG tiles to 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'.

gotcha LeafletWidget 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. ↓

fix Use forms.PointField(widget=LeafletWidget()) in your form or model form.

deprecated The 'leaflet.extras' module (ExtraAdminMixin, etc.) is deprecated in favor of directly using LeafletGeoAdmin or custom admin. It may be removed in a future release. ↓

fix Replace 'from leaflet.extras import LeafletGeoAdmin' with 'from leaflet.admin import LeafletGeoAdmin'.

Imports

LeafletWidget

wrong

from leaflet import LeafletWidget

correct

from leaflet.forms.widgets import LeafletWidget

LeafletWidget is in forms.widgets submodule.

LeafletGeoAdmin

wrong

from leaflet.contrib.admin import LeafletGeoAdmin

correct

from leaflet.admin import LeafletGeoAdmin

No contrib module; admin is top-level under leaflet.

display_messages
wrong
```
from leaflet import display_messages
```
correct
```
from leaflet.forms.widgets import display_messages
```
display_messages is a function inside forms.widgets, not top-level.

Quickstart

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)