Django Map Widgets

0.5.2 verified Fri May 01 auth: no python

A Django library providing configurable and user-friendly map widgets for GeoDjango geometry fields. Supports Google Maps, Leaflet, and MapBox interactive maps with point, geometry, and inline formset widgets. Current version 0.5.2, released March 2025. Active development with regular releases.

pip install django-map-widgets

Common errors

error django.core.exceptions.ImproperlyConfigured: django.contrib.gis is not installed ↓

cause Missing 'django.contrib.gis' in INSTALLED_APPS.

fix

Add 'django.contrib.gis' to INSTALLED_APPS and ensure GDAL is installed.

error AttributeError: 'NoneType' object has no attribute 'items' ↓

cause MAP_WIDGETS settings dict is missing or misconfigured.

fix

Define MAP_WIDGETS in settings.py with at least one provider configuration.

error ModuleNotFoundError: No module named 'map_widgets' ↓

cause Package not installed or not in virtual environment.

fix

Run pip install django-map-widgets and ensure virtual env is activated.

Warnings

breaking v0.5.0 introduced a new settings structure. Old settings like GOOGLE_MAP_API_KEY no longer work; use MAP_WIDGETS dict instead. ↓

fix Replace MAP_WIDGETS = {'GooglePointFieldWidget': (('zoom', 15),)} and API key under 'GoogleMaps' key.

breaking v0.5.2 removed `id` and `name` from template context in BaseGeometryWidget.get_context() for Django 6.0 compatibility. If you override get_context(), you must call super() and handle context. ↓

fix Ensure custom widget get_context() calls super().get_context(attname, ...) and re-add id/name if needed.

deprecated GooglePlaceAutocompleteOptions settings have changed. Old 'autocomplete' key may be ignored. ↓

fix Use new structure inside MAP_WIDGETS['GooglePointFieldWidget'] tuple.

gotcha Missing django.contrib.gis in INSTALLED_APPS or GDAL not installed causes silent failures. ↓

fix Ensure 'django.contrib.gis' is in INSTALLED_APPS and GDAL library is installed.

gotcha When using ManifestStaticFilesStorage, run collectstatic after installation. v0.5.1 fixed a bug that caused errors during collectstatic. ↓

fix Upgrade to 0.5.1+ or manually copy static files.

Imports

GooglePointFieldWidget

wrong

from map_widgets import GooglePointFieldWidget

correct

from map_widgets.widgets import GooglePointFieldWidget

Widgets live in map_widgets.widgets module, not top-level.

MapBoxPointFieldWidget

wrong

from map_widgets.mapbox import MapBoxPointFieldWidget

correct

from map_widgets.widgets import MapBoxPointFieldWidget

All widget classes import from map_widgets.widgets.

LeafletPointFieldWidget

wrong

from map_widgets.leaflet import LeafletPointFieldWidget

correct

from map_widgets.widgets import LeafletPointFieldWidget

Leaflet widget also in widgets module.

MAP_WIDGETS
```
from map_widgets import MAP_WIDGETS
```
Settings dict imported from map_widgets; not a class.

Quickstart

Basic setup for Google Maps point widget; replace API key via environment variable.

# settings.py
INSTALLED_APPS = [
    'django.contrib.gis',
    'map_widgets',
]

MAP_WIDGETS = {
    "GooglePointFieldWidget": (
        ("zoom", 15),
        ("mapCenterLocation", [40.7128, -74.0060]),
        ("GooglePlaceAutocompleteOptions", {}),
    ),
    "GoogleMaps": {
        "apiKey": os.environ.get('GOOGLE_MAPS_API_KEY', ''),
    }
}

# models.py
from django.contrib.gis.db import models
class Location(models.Model):
    point = models.PointField()
    address = models.CharField(max_length=255)

# admin.py
from django.contrib.gis import admin
from .models import Location
from map_widgets.widgets import GooglePointFieldWidget

class LocationAdmin(admin.GISModelAdmin):
    list_display = ('address',)
    formfield_overrides = {
        models.PointField: {"widget": GooglePointFieldWidget}
    }

admin.site.register(Location, LocationAdmin)