Django ORM Lens

See your entire Django schema — in your editor, in your terminal, and from your AI agent.

Every app. Every model. Every field. Every relationship. Grouped, navigable, and one keystroke away from a live ER diagram.

⚡ Install

VS Code / Cursor / Windsurf / any Code fork:

code --install-extension frowningdev.django-orm-lens

Or search Django ORM Lens in the Extensions view.

Terminal & AI coding agents:

pip install django-orm-lens              # CLI only
pip install "django-orm-lens[mcp]"       # + MCP server for AI agents

Requires Python 3.9+. Zero runtime dependencies for the CLI.

Related MCP server: django-mcp-inspector

🎯 The problem

You open a Django project. It has 20 apps. You need to answer a simple question:

"Which app owns the Order model, and how is it connected to User?"

Today, that means: Ctrl+P, "models", scroll through 30 hits, open five files, Ctrl+F for class Order, read through 400 lines of ForeignKey('otherapp.Something') strings, try to remember what you learned two files ago.

Half a day gone. Every time. On every project.

✨ With Django ORM Lens

📚 A tree of everything

Every app → every model → every field → every Meta option. Grouped by application, sorted alphabetically, expandable.

Icons distinguish CharField from ForeignKey from ManyToManyField at a glance.

🕸️ A live ER diagram

One command opens a Mermaid entity-relationship diagram of your entire schema. Watch it redraw as you edit. Export to SVG.

ForeignKey, OneToOneField, and ManyToManyField become proper cardinality arrows.

🔎 Hover for relations

Hover over ForeignKey('app.Model') in any Python file → a card pops up with the target model's fields, relations, and a "Jump to" link. No Ctrl+F, no file dialog.

🧭 Jump-to-definition

Click any field in the tree → cursor lands on the exact line. Filter the tree by app or model name. Split models/ packages are fully supported.

⚡ Zero configuration

No DJANGO_SETTINGS_MODULE. No runserver. Parses models.py statically. Works with a broken venv, a missing dependency, or on someone else's laptop.

🎨 Native VS Code UI

Dark theme. Light theme. Your theme. Follows your icon theme, your font, your key bindings. Nothing garish, nothing branded.

📸 What it looks like

🤖 For terminals and AI coding agents

The same parser that powers the VS Code extension ships as a standalone Python package — with an optional MCP (Model Context Protocol) server so any MCP-compatible AI agent can navigate your Django schema without importing Django or booting your app.

CLI

django-orm-lens scan -f json          # every app, every model, every field
django-orm-lens describe blog.Post    # one model in Markdown
django-orm-lens hover blog.Post       # compact hover card
django-orm-lens list | fzf            # flat app.Model — pipes anywhere
django-orm-lens er > schema.mmd       # Mermaid ER diagram

Every command accepts --path <dir> and --exclude <glob>.

MCP server

Register it once with your agent and it exposes five read-only tools:

# Start it directly
django-orm-lens-mcp

# Or via the CLI subcommand
django-orm-lens mcp

Set DJANGO_ORM_LENS_ROOT=/abs/path/to/project to point it anywhere.

🔌 Integrations

Example: Cursor / any MCP client

{
  "mcpServers": {
    "django-orm-lens": {
      "command": "django-orm-lens-mcp",
      "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
    }
  }
}

🚀 Get started (30 seconds)

In VS Code:

1. code --install-extension frowningdev.django-orm-lens

2. Open a folder with a manage.py or models.py

3. Click the Django ORM Lens icon in the activity bar

4. Expand apps → models → fields

5. Click the type-hierarchy icon at the top of the panel → ER diagram opens beside your code

In a terminal:

pip install django-orm-lens
cd my-django-project
django-orm-lens scan -f table

As an AI agent tool:

pip install "django-orm-lens[mcp]"

…then register django-orm-lens-mcp in your agent's MCP config (see the Integrations table above).

No settings screen. No sign-in. No telemetry.

🤔 How is this different?

⚙️ Configuration

The defaults are opinionated and sensible. If you need to tweak:

// .vscode/settings.json
{
  "djangoOrmLens.excludeGlobs": [
    "**/migrations/**",
    "**/node_modules/**",
    "**/venv/**",
    "**/.venv/**",
    "**/env/**"
  ],
  "djangoOrmLens.autoRefresh": true
}

🧭 Commands

Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and type "Django ORM Lens":

🗺️ Roadmap

Shipped

• Sidebar tree grouped by app

• Live Mermaid ER diagram

• Hover cards over ForeignKey('app.Model')

• Filter tree by name

• Split models/ package support

• Export ER diagram as SVG

• Python CLI + MCP server for terminals and AI agents

• Welcome view for empty workspaces

• Path-safe jump-to-definition and sanitized hover markdown

Next (v0.3.0)

• CodeLens above each class Model: N relations · N fields · Open ERD

• Edge labels on the diagram: CASCADE, SET_NULL, PROTECT, related_name

• Zoom + minimap + auto-layout inside the webview

• Named color themes (default / ocean / sunset / forest / dark)

• App / model toggle checkboxes to declutter huge schemas

Later

• Migration dependency graph

• ORM query autocomplete inside .filter()/.exclude()/.annotate()

• Third-party field support (django-mptt, django-taggit, django-model-utils)

• JetBrains / PyCharm plugin (if there is demand)

Vote by 👍-ing the corresponding issue.

❓ FAQ

🆘 Support

• 🐛 Bug reports — GitHub Issues (please include a minimal models.py snippet)

• 💡 Feature requests / ideas — GitHub Discussions

• 📝 Marketplace reviews — rate the extension (the fastest signal that keeps this project moving)

• 🐍 PyPI page — pypi.org/project/django-orm-lens

• 💚 Sponsor — github.com/sponsors/FROWNINGdev

📜 License

MIT © FROWNINGdev

Made for developers who care about their codebase.

Marketplace · PyPI · GitHub · Issues · Discussions · Sponsor