概要
Django Debug Toolbarを導入し、settings.pyとurls.pyへ必要な設定を追加する手順を整理する。
Django Debug Toolbarは、リクエスト、レスポンス、SQL、テンプレートなどの情報をブラウザ上で確認できる開発支援ツールとなる。
開発時の調査には便利だが、本番環境や公開サーバーでの利用を想定して強化されたツールではないため、開発環境だけで有効にすることが重要になる。
この記事の構成
- 対象環境と利用上の注意
本文記載時の環境と現在そのまま利用できない箇所を確認。 - 作業時の注意点
設定変更やコマンド実行前に確認しておきたい注意点を整理。 - django-debug-toolbarの導入
django-debug-toolbarの導入の手順と確認ポイントを整理。 - django-debug-toolbarの設定追加
django-debug-toolbarの設定追加の手順と確認ポイントを整理。 - Debug Toolbarの表示確認
Debug Toolbarの表示について、確認する項目と結果の見方を整理。
対象環境と利用上の注意
- 本文記載時の環境
掲載画像はDjango 2.0.2と当時のDjango Debug Toolbarを利用した旧環境。
設定例は現行版の公式手順に合わせて補足している。 - 確認時期
2026年8月にDjango Debug Toolbarの公式資料と照合。
現行版を新規環境へ導入する一連の手順は再実行していない。 - 現在そのまま利用できない箇所
対応するPython・Djangoのバージョン、URL設定、ミドルウェア要件はDjango Debug Toolbarの版によって異なる。
インストール前に利用する版の公式ドキュメントを確認し、本番環境では有効にしない。
作業時の注意点
- Toolbarが出ない
DEBUG、INTERNAL_IPS、URL設定、MIDDLEWAREの順に確認。 - CSSやJavaScriptが読み込めない
staticfilesの設定とブラウザーの開発者ツールを確認。 - 設定順序
DebugToolbarMiddlewareは早い位置に置き、レスポンスを圧縮するミドルウェアより後に置く。 - 本番利用
デバッグ情報を公開しないよう、開発用途に限定する。
実施内容
django-debug-toolbarの導入
django-debug-toolbarは、セッション、リクエスト/レスポンス、実行したSQLなどをリクエスト単位で確認できる開発支援パッケージとなる。
-
django-debug-toolbarのインストール
仮想環境を有効にしてから、公式手順どおりpython -m pipでインストール。
利用中のPython・Djangoに対応するバージョンは、インストール前に公式ドキュメントで確認。
※ 仮想環境とDjangoの準備は、Djangoインストールを参照。$ source /var/www/vops/bin/activate (vops) $ python -m pip install django-debug-toolbar -
Django側の前提設定
通常のstartprojectで作成したプロジェクトでは設定済みだが、INSTALLED_APPSにdjango.contrib.staticfilesがあり、TEMPLATESのDjangoTemplatesバックエンドでAPP_DIRS=Trueになっていることを確認。
django-debug-toolbarの設定追加
-
settings.pyの設定
settings.pyの最低限必要な設定を変更。-
DEBUGモードの変更
開発環境でDEBUG=Trueとなるように設定。
本番環境と設定を共有している場合は、環境変数や設定ファイルを分け、本番で誤って有効にならないようにする。DEBUG = True -
INSTALLED_APPSへ追加
INSTALLED_APPSに"debug_toolbar"を追記する。INSTALLED_APPS = [ # ... "django.contrib.staticfiles", "debug_toolbar", ] -
MIDDLEWAREへ追加
MIDDLEWAREに"debug_toolbar.middleware.DebugToolbarMiddleware"を追記する。公式手順ではできるだけ早い位置が推奨されるが、GZipMiddlewareなどレスポンスをエンコードするミドルウェアを使用している場合は、その後ろに置く。MIDDLEWARE = [ # "django.middleware.gzip.GZipMiddleware", # 使用する場合はこの後ろ "debug_toolbar.middleware.DebugToolbarMiddleware", # ... ] -
INTERNAL_IPSの追加
INTERNAL_IPS = ["127.0.0.1"]既定の表示判定では、Djangoが認識する接続元IPが
INTERNAL_IPSに含まれる場合だけToolbarが表示される。
Docker、リバースプロキシ、別の開発サーバーを利用する場合は見えるIPが変わるため、公式ドキュメントのSHOW_TOOLBAR_CALLBACKも含めて環境に合わせて設定。
単に常にTrueを返す設定を公開環境へ置かないよう注意。
-
-
urls.pyの設定
現在の公式手順では、debug_toolbar_urls()を利用してToolbar用URLを追加できる。
既定では__debug__/がプレフィックスとなる。from debug_toolbar.toolbar import debug_toolbar_urls urlpatterns = [ # アプリケーションのURL ] + debug_toolbar_urls()使用しているバージョンやプロジェクト方針によってURLを明示する場合は、古い
url()ではなくpath()を使用。from django.conf import settings from django.urls import include, path if settings.DEBUG: urlpatterns += [ path("__debug__/", include("debug_toolbar.urls")), ]以上で設定は完了。
Debug Toolbarの表示確認
管理者画面や作成したWebアプリの画面に接続すると右側にDebug Toolbarが表示される。
画像はDjango 2.0.2と当時のDjango Debug Toolbarによる表示例であり、現在のバージョンではパネル名や外観が異なる場合がある。
「画面右側に調査用パネルが挿入される」という位置関係の参考として利用できる。
-
Toolbarが表示されない場合の確認順序
DEBUG=Trueであり、接続元IPがINTERNAL_IPSに含まれているか。- レスポンスのContent-Typeが
text/htmlまたはapplication/xhtml+xmlで、HTMLに閉じ</body>タグがあるか。 DebugToolbarMiddleware、URL、django.contrib.staticfilesの設定に漏れがないか。- ブラウザーの開発者ツールに、JavaScriptのMIMEタイプやCORS、404エラーが出ていないか。
パッケージ内のstaticディレクトリを手動コピーすると、更新時に古いファイルが残る原因になる。CSSやJavaScriptが読み込めない場合はコピーで回避せず、Djangoのstaticfiles設定や配信サーバーのMIMEタイプ・CORS設定を確認する。
まとめ
- Django Debug Toolbarは、Django開発時の調査を助けるデバッグツールとなる。
- 導入には、パッケージインストール、settings.py、urls.pyの設定が必要になる。
- 便利な反面、内部情報を表示するため本番環境では無効化。