Registry / web-framework / django-debug-toolbar

django-debug-toolbar

library7.1.1pypypi✓ verified 26d ago

Django Debug Toolbar is a configurable set of panels that display various debug information about the current request/response in Django applications. It is actively maintained by the Django Commons organization, with new releases typically coming out every few months, often tied to Django's release cycle and Python version support. The current version is 6.3.0.

web-framework

pip install django-debug-toolbar

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · DJANGO-DEBUG-TOOLB

django-debug-toolbar

web-frameworkpythonv7.1.1

Install

3.6s avg

Import

—

Disk

67MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v7.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 68.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.6s · import 0.000s · 69MB

67MB installed

● package 67MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DebugToolbarMiddleware

✓ from debug_toolbar.middleware import DebugToolbarMiddleware

✗ from debug_toolbar.middleware import DebugToolbarMiddleware

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 ... ]

Debug

Known issues

breakingVersion 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.

affects: >=6.0.0

breakingVersion 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.

affects: >=5.0.0

gotchaThe `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.

affects: All versions

gotchaThe 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`.

affects: All versions

deprecatedAs 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.

affects: >=6.2.0

gotchaThe 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.

affects: All versions

gotchaThe Django settings module must be configured before any settings, including those for django-debug-toolbar, can be accessed. This typically involves defining the `DJANGO_SETTINGS_MODULE` environment variable or calling `settings.configure()` in your application setup.

fix

Ensure the `DJANGO_SETTINGS_MODULE` environment variable is set to your project's settings file (e.g., `your_project.settings`), or that `settings.configure()` is called at an appropriate point in your application's bootstrap process.

affects: All versions

gotchaDjango requires a settings module to be configured before any settings can be accessed. This is typically achieved by setting the `DJANGO_SETTINGS_MODULE` environment variable (e.g., `myproject.settings`) or by explicitly calling `django.conf.settings.configure()` in your application's bootstrap. Without configured settings, the Django application, including the debug toolbar, cannot function.

fix

Ensure the `DJANGO_SETTINGS_MODULE` environment variable is correctly set to your project's settings module path (e.g., `export DJANGO_SETTINGS_MODULE=myproject.settings`) or ensure `django.conf.settings.configure()` is called appropriately during application initialization.

affects: All versions

Upgrade

Version history

7.1.1latest on PyPI · released Aug 14, 2026

Audit

Dependencies

DjangorequiredCore dependency for the debug toolbar to function. Requires Django 4.2+ for current versions, compatible with Python >=3.10.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/django-commons/django-debug-toolbar ↗

packagehttps://pypi.org/project/django-debug-toolbar/ ↗

docshttps://django-debug-toolbar.readthedocs.io/ ↗

changeloghttps://django-debug-toolbar.readthedocs.io/en/latest/changes.html ↗