Python + Django

This guide covers adding debugger to a Django project. The setup takes one line in your settings file.

Django official docs

Prerequisites

• Python 3.10 or later
• Django 4.2 or later

Install

pip install ephem-debugger[django]

Or with uv:

uv add ephem-debugger[django]

Set up

Add the middleware to your Django settings:

# settings.py
MIDDLEWARE = [
    "ephem_debugger_py.middleware.django.DebuggerMiddleware",
    # ... other middleware
]

# Optional: set the port (defaults to 8000)
DEBUGGER_PORT = 8000

One line in MIDDLEWARE handles everything — log store, IPC bridge, console capture, and HTTP request logging.

What gets captured

• HTTP requests — method, path, status code, and latency for every request
• Root logger output — the debugger handler is added to the root Python logger, capturing all logging.info(), logging.error(), etc. calls throughout your Django app

Verify

Start your server:

python manage.py runserver

Open another terminal and query:

npx dbg status

pnpm dlx dbg status

bun x dbg status

yarn dlx dbg status

npx dbg server console

pnpm dlx dbg server console

bun x dbg server console

yarn dlx dbg server console

Production safety

Django only runs the middleware when it's in the MIDDLEWARE list. Guard it for production:

# settings.py
MIDDLEWARE = [...]

import os
if os.getenv("DEBUG") == "1":
    MIDDLEWARE.insert(0, "ephem_debugger_py.middleware.django.DebuggerMiddleware")

Browser support

If your application serves HTML pages, the debugger automatically captures browser-side data. The middleware:

• Serves the browser client script at /_/d.js
• Handles browser log ingest at POST /_/d
• Auto-injects script tags into HTML responses before </body>

No additional setup is needed. Query browser data with:

npx dbg browser console

pnpm dlx dbg browser console

bun x dbg browser console

yarn dlx dbg browser console

npx dbg browser errors

pnpm dlx dbg browser errors

bun x dbg browser errors

yarn dlx dbg browser errors

npx dbg browser network

pnpm dlx dbg browser network

bun x dbg browser network

yarn dlx dbg browser network

npx dbg browser cookies

pnpm dlx dbg browser cookies

bun x dbg browser cookies

yarn dlx dbg browser cookies

npx dbg browser storage

pnpm dlx dbg browser storage

bun x dbg browser storage

yarn dlx dbg browser storage

Full example

See the complete working example at examples/python/django.