django-devbar 0.7.0

Lightweight performance devbar for Django

django-devbar

[!WARNING] This package is experimental and may introduce breaking changes in minor versions.

Lightweight performance devbar for Django. Shows DB query count, query duration, application time, and detects similar and duplicate queries with visual severity indicators.

Showcase

Normal operation – showing query count, duration, and application time:

Similar and duplicate queries detected – severity indicators and details shown:

[optional] Chrome extension - showing detailed metrics in DevTools panel:

Motivation

While Django Debug Toolbar is a proven tool trusted by countless projects, django-devbar explores a different approach to development debugging:

• Minimal setup — just add middleware, nothing else required
• Browser DevTools integration — Chrome extension panel works with any response type, including JSON
• Zero extra dependencies — only requires Django
• Lower overhead — no extra requests to debug endpoints
• Non-intrusive — HTML bar is optional; works via headers and DevTools panel alone

Installation

# Using uv (recommended)
uv add --dev django-devbar

# Or using pip
pip install django-devbar

Add to your middleware early. For example:

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    # ...
]

if DEBUG:
    idx = MIDDLEWARE.index("django.middleware.security.SecurityMiddleware")
    MIDDLEWARE.insert(idx + 1, "django_devbar.DevBarMiddleware")

This keeps the middleware active only in development and avoids import errors if the package isn't installed in production.

Configuration

All settings are optional. Configure via a DEVBAR dict in your Django settings:

DEVBAR = {
    "POSITION": "bottom-right",  # bottom-right (default), bottom-left, top-right, top-left
    "SHOW_BAR": None,  # follows DEBUG; set True/False to override
    "ENABLE_DEVTOOLS_DATA": None,  # follows DEBUG; set True/False to override
    "DEVTOOLS_HEADER_MAX_BYTES": 6144,  # max bytes for DevBar-Data header payload
    "DEVTOOLS_MAX_QUERIES": None,  # optional hard cap for q/dup entries sent to DevTools
}

Response Headers

Django DevBar adds HTTP response headers with performance metrics:

• Server-Timing (always present) – Standard HTTP header with database, application, and total time metrics. Visible in Chrome DevTools Network tab under Timing.

An additional header is included by default in DEBUG mode:

• DevBar-Data - JSON header with comprehensive metrics including similar and duplicate query details
  • Query-level flags are embedded in q entries (dup and sim)
  • Payload is automatically truncated to fit DEVTOOLS_HEADER_MAX_BYTES
  • When truncated, response includes metadata keys: tr, q_total, q_sent

This is useful for:

• API endpoints where the HTML overlay can't be displayed
• Automated testing to assert performance metrics (e.g., fail CI if query count exceeds a limit)
• Browser extensions that need detailed duplicate query information

Server-Timing format

Server-Timing: db;dur=87.50, app;dur=41.30, total;dur=128.80

Chrome Extension

View Django DevBar metrics directly in Chrome DevTools with the official extension.

See chrome-extension/README.md for more details.