Flask Debug Toolbar

0.16.0 · active · verified Sat Apr 11

Flask-DebugToolbar is a Flask extension that provides a customizable toolbar overlay for debugging web applications. It's an active project within the Pallets Community Ecosystem, currently at version 0.16.0, and releases updates periodically to maintain compatibility with Flask and Python.

Warnings

breaking Version 0.16.0 drops support for Python 3.7. Applications running on Python 3.7 will need to upgrade their Python version to 3.8 or newer to use Flask-DebugToolbar 0.16.0 and above.
Fix: Upgrade your Python environment to 3.8 or a later version.
breaking Version 0.16.0 requires Flask version 2.3.0 or higher. Older Flask versions are incompatible.
Fix: Ensure your Flask application is running Flask 2.3.0 or newer. For Flask 2.2.x, use Flask-DebugToolbar 0.15.x.
gotcha Version 0.14.0 was released with a missing `packaging` dependency, causing an `ImportError`. This was fixed in 0.14.1.
Fix: Do not use version 0.14.0; upgrade directly to 0.14.1 or newer.
deprecated The `__version__` attribute has been removed from the library as of 0.16.0.
Fix: Avoid direct access to `flask_debugtoolbar.__version__`. Instead, rely on package management tools or `importlib.metadata` to query the installed version if programmatic access is needed.
gotcha The Debug Toolbar will only be displayed if `app.debug = True` is set and a `SECRET_KEY` is configured in `app.config`. Ensure `app.debug = True` is set *before* initializing `DebugToolbarExtension`.
Fix: Set `app.debug = True` and `app.config['SECRET_KEY'] = 'your_secret_key'` (use an environment variable for production) before `toolbar = DebugToolbarExtension(app)`.
gotcha The toolbar requires a `<body>` tag in the HTML response to inject its content. It may not appear on pages returning plain strings or non-HTML content.
Fix: Ensure your Flask view functions return HTML that includes a `<body>` tag, typically by using `render_template`.
gotcha The `Blinker` dependency was dropped in 0.16.0. If you have custom extensions or code relying on `Blinker` signals specifically related to the debug toolbar, this change might affect you, though it's generally an internal dependency removal.
Fix: Review custom integrations that might have implicitly relied on `Blinker` being present as a `flask-debugtoolbar` dependency. Most users will not be affected.

Install

pip install flask-debugtoolbar Install with pip

Imports

DebugToolbarExtension

from flask_debugtoolbar import DebugToolbarExtension

Quickstart

To enable the Flask Debug Toolbar, initialize it with your Flask application. Crucially, set `app.debug = True` and configure a `SECRET_KEY` in `app.config`. The toolbar is automatically injected into HTML responses when debug mode is active. For full functionality, ensure your responses contain a `<body>` tag. Using `render_template` is recommended.

from flask import Flask, render_template
from flask_debugtoolbar import DebugToolbarExtension
import os

app = Flask(__name__)
app.debug = True  # Enable debug mode
app.config['SECRET_KEY'] = os.environ.get('FLASK_SECRET_KEY', 'a_very_secret_key_for_dev')

# Optional: Configure toolbar settings
# app.config['DEBUG_TB_INTERCEPT_REDIRECTS'] = False

toolbar = DebugToolbarExtension(app)

@app.route('/')
def index():
    return '<body><h1>Hello, Flask!</h1></body>'

@app.route('/hello/<name>')
def hello(name):
    return render_template('hello.html', name=name) # Ensure templates are in 'templates/' folder

# Example of running the app
# if __name__ == '__main__':
#     # You would typically run with 'flask run --debug' or a WSGI server
#     # For this quickstart, ensure FLASK_APP is set to your app file (e.g., 'app.py')
#     # and then run 'flask run --debug'
#     pass

view raw JSON →