Registry / web-framework / flask-debugtoolbar

flask-debugtoolbar

library0.16.0pypypi✓ verified 24d ago

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.

web-framework

pip install flask-debugtoolbar

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · FLASK-DEBUGTOOLBAR

flask-debugtoolbar

web-frameworkpythonv0.16.0

Install

2.3s avg

Import

470ms

Disk

23MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.16.0 · 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.490s · 24.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.3s · import 0.450s · 25MB

23MB installed

● package 23MB

Code

Verified usage

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

DebugToolbarExtension

✓ from flask_debugtoolbar import DebugToolbarExtension

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

Debug

Known issues

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

affects: >=0.16.0

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

affects: >=0.16.0

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

affects: 0.14.0

deprecatedThe `__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.

affects: >=0.16.0

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

affects: All versions

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

affects: All versions

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

affects: >=0.16.0

Errors

Common errors & fixes

flask-debugtoolbar not showing

The Flask-DebugToolbar often doesn't appear because the Flask application is not running in debug mode (`app.debug = True`) or a `SECRET_KEY` is not configured for Flask session cookies.

fix

Ensure that `app.debug = True` is set before initializing the toolbar and that `app.config['SECRET_KEY']` is assigned a secret string. For example:
```python
from flask import Flask
from flask_debugtoolbar import DebugToolbarExtension

app = Flask(__name__)
app.debug = True
app.config['SECRET_KEY'] = 'a-very-secret-key'
toolbar = DebugToolbarExtension(app)
```

ImportError: No module named flask_debugtoolbar

This error occurs when the `flask-debugtoolbar` package is not installed in the active Python environment or is not accessible in the Python path.

fix

Install the package using pip: `pip install flask-debugtoolbar`.

ImportError: cannot import name 'url_quote_plus' from 'werkzeug.urls'

This error arises due to an incompatibility between `flask-debugtoolbar` and newer versions of `Werkzeug` (Flask's dependency), where `url_quote_plus` was removed or moved in `werkzeug.urls`.

fix

Downgrade Flask and Werkzeug to versions compatible with `flask-debugtoolbar` 0.16.0. A common workaround is `pip install "flask<=2.3.3" "werkzeug<=2.3.7"` or upgrading `flask-debugtoolbar` if a newer version is available with the fix.

Upgrade

Version history

0.16.0latest on PyPI · released Sep 28, 2024

Audit

Dependencies

FlaskrequiredCore web framework dependency.

packagingrequiredRequired for package metadata parsing (added post 0.14.0).

Flask-SQLAlchemyoptionalOptional: Required for the SQLAlchemy debug panel to show queries.

PygmentsoptionalOptional: Required for SQL syntax highlighting in the SQLAlchemy debug panel.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/pallets-eco/flask-debugtoolbar ↗

packagehttps://pypi.org/project/flask-debugtoolbar/ ↗

docshttps://flask-debugtoolbar.readthedocs.io ↗

changeloghttps://github.com/pallets-eco/flask-debugtoolbar/releases/ ↗