CRUD.cloud

Setup django-debug-toolbar in a dockerized app

Update, October 2026: I'm keeping this article as I wrote it in 2022. Some things have changed since then, so read Before You Try This Today before you copy the commands.

To install and set up django-debug-toolbar you can follow the instruction from the official documentation{:target="_blank"} .

Works fine for "classic" application setup locally but if you use Docker to spin up your project locally, you will find out that it does not work.

Config

There are more configuration to add in order to make it play nice with Docker.

The Django Debug Toolbar checks the IP address of incoming requests to determine if it should show the toolbar. By default, it only allows requests from 127.0.0.1.

When running your app in Docker, your requests might originate from a different internal IP address. You can allow these requests by modifying INTERNAL_IPS in your settings.py

# settings.py

# DEBUG_TOOLBAR
INTERNAL_IPS = [
  "127.0.0.1",
]

# Include Docker's default internal IP range (e.g., 172.16.0.0/12)
docker_host_ip = os.environ.get("DOCKER_HOST_IP", "172.17.0.1")
INTERNAL_IPS.append(docker_host_ip)

DEBUG_TOOLBAR_CONFIG = {
  # Always show toolbar if debug is true
  "SHOW_TOOLBAR_CALLBACK": lambda request: True,
  # Disable redirect interception for better performance
  "INTERCEPT_REDIRECTS": False,
}

HTMX

And if you are using HTMX, don't forget to add the script bellow in your base template:

{% if debug %}
<script>
  if (typeof window.htmx !== "undefined") {
    htmx.on("htmx:afterSettle", function (detail) {
      if (
        typeof window.djdt !== "undefined"
        && detail.target instanceof HTMLBodyElement
      ) {
        djdt.show_toolbar();
      }
    });
  }
</script>
{% endif %}

Before You Try This Today

Added on 2026-10-20. The article above is unchanged since 2022-11-06; these are the gotchas you may hit if you follow it today.

  • lambda request: True ignores DEBUG. It shows the toolbar on every request, so the INTERNAL_IPS lines above it do nothing. The toolbar docs say a custom callback must return False when DEBUG is False, and that the toolbar isn't hardened for production: a leaked SECRET_KEY can let someone run SQL through the SQL panel. At minimum use lambda request: settings.DEBUG.
  • Use the built-in Docker callback instead of a hard-coded IP. 172.17.0.1 is only Docker's default bridge. Compose networks usually get another subnet, so the toolbar stays hidden. Current versions ship "SHOW_TOOLBAR_CALLBACK": "debug_toolbar.middleware.show_toolbar_with_docker", which finds the gateway IP for you. Only use it inside a container.
  • INTERCEPT_REDIRECTS no longer exists. Redirects are handled by the RedirectsPanel, which is disabled by default, so you can drop that line.
  • The snippet needs import os at the top of settings.py.
  • Wire up the URLs with the current helper: from debug_toolbar.toolbar import debug_toolbar_urls, then urlpatterns = [...] + debug_toolbar_urls(). Also add the middleware early in MIDDLEWARE, but after any middleware that encodes the response, like GZipMiddleware.
  • The toolbar blocks your tests by default. It refuses to run when it detects a test run (IS_RUNNING_TESTS). Load it only in your development settings, or set IS_RUNNING_TESTS = False deliberately.
  • The {:target="_blank"} after the documentation link is MkDocs syntax. Outside MkDocs it shows up as literal text.

References

Links checked on 2026-10-20.