DEV Community

Ajit Kumar
Ajit Kumar

Posted on

Zero-Effort ER Diagrams in Django: Auto-Generate Directly From Your Models

#django #diagram #python #mermaid

When a Django project starts small, model relationships are easy to understand.
But as the project grows — new apps, foreign keys everywhere, business logic stacked across modules — suddenly:

❗ Understanding how models relate becomes harder than reading the source code itself.

This is where Entity-Relationship Diagrams (ERDs) become incredibly important.
A good ERD helps every developer (new or old) understand:

✔ How models depend on each other
✔ Where foreign keys and many-to-many relations exist
✔ Effects of cascading deletes
✔ Where circular dependencies might cause migrations to fail

Yet many teams never update ERDs after the first version, because manually drawing diagrams in Draw.io / Lucidchart / Figma becomes unmaintainable.

💡 The solution? Generate ER diagrams automatically from Django models — as code or as images — directly from your project.

Not only can this live documentation be added to the repo, it can also be generated automatically in CI/CD, ensuring your docs always match your models.

🏆 3 Tools That Cover 100% of Real Use Cases

Goal Best Format Recommended Tool
Auto-generate PNG / SVG diagrams DOT → PNG django-extensions
Editable UML diagrams PlantUML django-models2puml
Documentation-friendly Markdown Mermaid django-diagram

🔥 1. Generate PNG / SVG ERD Using django-extensions

This is the most popular and most reliable method.

🧩 Install Required Packages 

pip install django-extensions
pip install pygraphviz   # or: pip install pydot
Enter fullscreen mode Exit fullscreen mode

➕ Enable It 

# settings.py
INSTALLED_APPS = [
    ...
    "django_extensions",
]
Enter fullscreen mode Exit fullscreen mode

▶️ Generate Diagram For All Apps 

./manage.py graph_models -a -o project_erd.png
Enter fullscreen mode Exit fullscreen mode

▶️ Generate Diagram For a Single App 

./manage.py graph_models blog -o blog_erd.png
Enter fullscreen mode Exit fullscreen mode

📌 Output example:
👉 Each model becomes a box
👉 ForeignKey / OneToOne / ManyToMany relationships become arrows
👉 Cascade / SET_NULL relationships are annotated

🌱 2. Generate PlantUML (.puml) — ERD as Editable Code

PlantUML is ideal if you want:

🔹 Review diffs in pull requests
🔹 Let architects propose changes without touching code
🔹 Render diagrams locally or in docs sites

📦 Install 

pip install django-models2puml
Enter fullscreen mode Exit fullscreen mode

▶️ Generate PlantUML 

./manage.py generatepuml --apps blog > blog_models.puml
Enter fullscreen mode Exit fullscreen mode

Example .puml structure:

@startuml
class Post {
    id: UUID
    title: CharField
}
Post "1" -- "*" Comment : has
@enduml
Enter fullscreen mode Exit fullscreen mode

This can be rendered via:

  • VS Code PlantUML plugin
  • PyCharm PlantUML support
  • PlantUML server / CLI
  • MkDocs, Sphinx, Docusaurus integrations

🧜 3. Generate Mermaid ER Diagrams for Markdown Docs

Mermaid diagrams render automatically on:

Platform Supported?
GitHub README ✔️
GitLab ✔️
Notion ✔️
Obsidian ✔️
MkDocs ✔️

📦 Install 

pip install django-diagram
Enter fullscreen mode Exit fullscreen mode

▶️ Generate Mermaid Markdown 

python -m django_diagram \
    --settings=megaproject.settings \
    --app=blog \
    --output=blog_erd.md
Enter fullscreen mode Exit fullscreen mode

Example output:

erDiagram
    Post ||--o{ Comment : has
Enter fullscreen mode Exit fullscreen mode

💡 VS Code tip: install “Markdown Preview Mermaid Support” to render diagrams visually.

🤖 Automate ERD Generation (Docs Always Up-To-Date)

Put this in your project root:

#!/bin/bash
export DJANGO_SETTINGS_MODULE="megaproject.settings"
export PYTHONPATH=$PWD:$PYTHONPATH

OUTPUT_DIR="docs/erd"
mkdir -p $OUTPUT_DIR

APPS=$(./manage.py showmigrations | awk -F' ' '{print $1}' | sort | uniq)

for app in $APPS; do
    ./manage.py graph_models $app -o "$OUTPUT_DIR/${app}.png"
done
Enter fullscreen mode Exit fullscreen mode

Add to CI/CD (GitHub Actions example):

- name: Generate ERD
  run: ./generate_erd.sh
- name: Upload ERD artifacts
  uses: actions/upload-artifact@v3
  with:
    path: docs/erd
Enter fullscreen mode Exit fullscreen mode

📌 Your ERD will now update itself whenever models change — zero effort.

🧾 Real Example: Before vs After Introducing Auto-Generated ERDs

Without ERDs With Auto-Generated ERDs
Onboarding new devs takes time New devs understand system in minutes
Model misunderstandings cause bugs Relationships are visually explicit
Circular dependencies missed Visible immediately in diagram
Hard to plan refactoring Bird’s eye view of all models
Docs always outdated Docs updated every commit via CI

🎯 Final Recommendation

If this is your priority Use
PNG / JPEG images for clients django-extensions (graph_models)
UML diagrams in code review django-models2puml
Markdown documentation django-diagram

Power move 🚀:
Generate Mermaid for README + PNG for documentation hosting + PlantUML for architecture review in CI/CD.

Note: Formatted with LLM Tool after research and using all approaches. :)

Top comments (0)