Django Debug Toolbar

Warnings

• breaking Version 6.0.0 significantly revamped how panel data is persisted, introducing configurable backends (memory, database). Custom panels or previous assumptions about panel data handling may require updates. Additionally, sensitive information is now filtered using `SafeExceptionReporterFilter.cleanse_setting()`.
  Fix: Review any custom panels and update logic for data storage according to the new panel data persistence system. Be aware of automatic sanitization of sensitive data in displayed information.
• breaking Version 5.0.0 dropped support for Python 3.8. The project moved to the Django Commons organization. Significant changes were made to the middleware for improved async compatibility, which might affect highly customized middleware setups or existing async applications.
  Fix: Ensure your project runs on Python 3.9+ (preferably 3.10+ for current versions of Django). Thoroughly test your middleware chain and async views after upgrading.
• gotcha The `INTERNAL_IPS` setting is mandatory for the toolbar to appear. By default, the toolbar only shows for requests originating from these specified IP addresses. If you're using Docker, WSL, a remote development environment, or a non-standard localhost setup, you must ensure your client's IP is included.
  Fix: Add `INTERNAL_IPS = ['127.0.0.1', '::1', 'your_dev_ip_here']` to your `settings.py`. For dynamic environments, consider using environment variables to populate this list.
• gotcha The placement of `DebugToolbarMiddleware` in your `MIDDLEWARE` list is crucial. It generally needs to be placed *after* any middleware that modifies the response (e.g., `CompressionMiddleware`, `CommonMiddleware`) but *before* middleware that expects a complete response and may prematurely close it.
  Fix: Place `'debug_toolbar.middleware.DebugToolbarMiddleware'` early in your `MIDDLEWARE` list, typically after `SecurityMiddleware` and `SessionMiddleware` but before other processing middleware like `CommonMiddleware`.
• deprecated As of version 6.2.0, `RedirectsPanel` has been deprecated in favor of the more robust `HistoryPanel`. While `RedirectsPanel` still functions, it is recommended to update your `DEBUG_TOOLBAR_PANELS` setting if you explicitly listed it.
  Fix: Replace `'debug_toolbar.panels.redirects.RedirectsPanel'` with `'debug_toolbar.panels.history.HistoryPanel'` in your `DEBUG_TOOLBAR_PANELS` setting if you have customized your panel list.
• gotcha The Django `DEBUG` setting must be set to `True` for the toolbar to activate and display. The toolbar will not render in production environments where `DEBUG` is `False`.
  Fix: Ensure `DEBUG = True` in your development `settings.py` file. Use separate settings files or environment variables to manage `DEBUG` for different environments.

Install

• pip install django-debug-toolbar Install stable version

Imports

• DebugToolbarMiddleware

  from debug_toolbar.middleware import DebugToolbarMiddleware

• debug_toolbar.urls

  import debug_toolbar

Quickstart

To quickly set up Django Debug Toolbar, first install the package. Then, modify your Django project's `settings.py` by adding `'debug_toolbar'` to `INSTALLED_APPS` and `'debug_toolbar.middleware.DebugToolbarMiddleware'` to `MIDDLEWARE`. Crucially, configure `INTERNAL_IPS` to include your development machine's IP address(es) for the toolbar to be visible. Finally, add the debug toolbar's URLs to your project's `urls.py`, typically conditional on `settings.DEBUG` being `True`.

# settings.py
import os

DEBUG = True # Essential for debug_toolbar to appear

INSTALLED_APPS = [
    # ... your other apps
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    
    "debug_toolbar", # Add debug_toolbar to your INSTALLED_APPS
]

MIDDLEWARE = [
    # ... Django's default middleware ...
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "debug_toolbar.middleware.DebugToolbarMiddleware", # Place early in middleware list
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
    # ... your custom middleware ...
]

# Configure INTERNAL_IPS for the toolbar to show up
INTERNAL_IPS = [
    "127.0.0.1",
    "::1", # IPv6 localhost
    # If running in Docker, WSL, or remotely, add your development machine's IP, e.g.,
    # "172.17.0.1", # Common for Docker host
    # os.environ.get("YOUR_DEV_IP", ""), # Dynamic IP example
]

# Optional: Customize toolbar behavior (e.g., disable panels)
DEBUG_TOOLBAR_CONFIG = {
    "DISABLE_PANELS": [
        "debug_toolbar.panels.redirects.RedirectsPanel" # Example: disable redirects panel
    ],
    "SHOW_TOOLBAR_CALLBACK": "debug_toolbar.utils.show_toolbar_callback",
}


# urls.py
from django.contrib import admin
from django.urls import path, include
from django.conf import settings

if settings.DEBUG:
    import debug_toolbar # Only import if DEBUG is True
    urlpatterns = [
        path("__debug__/", include(debug_toolbar.urls)),
        path("admin/", admin.site.urls),
        # ... your other app paths ...
    ]
else:
    urlpatterns = [
        path("admin/", admin.site.urls),
        # ... your other app paths ...
    ]