django-lumen

Visualize your Django models as an interactive ERD diagram in the browser. No external diagram library — the diagram is pure vanilla JS + SVG rendered at request time from the live Django model registry.

Requirements

• Python 3.10+
• Django 3.2+

Installation

pip install django-lumen

Setup

1. Add django_lumen to INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    ...
    "django_lumen",
]

2. Mount the URLs in your root urls.py:

# urls.py
from django.urls import path, include

urlpatterns = [
    ...
    path("lumen/", include("django_lumen.urls")),
]

3. Run migrations:

python manage.py migrate

4. Start the development server and open http://localhost:8000/lumen/.

Access control

The diagram is only accessible to users with is_active = True and is_staff = True. Other users are redirected to the login page.

App filter

The sidebar lists every app present in the diagram. Clicking an app name filters the diagram to show only models belonging to that app plus any models they have direct relations to. Click again to deselect. Multiple apps can be selected at once — when no app is selected, all models are shown.

Right-clicking an app name marks it as excluded (shown in red with strikethrough). Excluded apps are completely hidden from the diagram and the preference is saved automatically. Right-click again to un-exclude.

Settings

Each staff user has their own saved preferences, accessible via the Settings link in the diagram header. The settings page provides three sections:

Managed tables — when enabled, models with managed = False in their Meta class are hidden from the diagram.

Show inheritance — when enabled, each model box displays its parent class(es) below the model name. The default Django base (models.Model) is not shown — only custom application-level parents are displayed.

Excluded models — a list of regex patterns matched against model names. Any model whose name matches at least one pattern is hidden. Patterns use Python re.search, so use ^/$ to anchor. Examples: ^Historical, Log$, Audit.

Excluded apps — checkboxes to permanently hide entire apps from the diagram. The following apps are hidden by default: auth, admin, sessions, contenttypes, django_lumen. Users can also right-click an app chip in the sidebar to exclude it directly from the diagram view.