Flask-DebugToolbar injects a debugging sidebar into your pages

Panels in a sidebar

The extension is described in one line as a Flask extension that injects debugging information into rendered HTML pages, presented as a sidebar with configurable panels of information. The sidebar model is the point, and it comes straight from the project's lineage. This is a port of the django-debug-toolbar, which is the reference implementation of the idea, so a developer arriving from Django will find the interaction familiar rather than having to learn a new debugging metaphor. The other thing worth noting is where the information comes from. The toolbar is injected into Jinja templates, which means the instrumentation lives at the template rendering step rather than in your views, and it works for any page that is rendered through Jinja, which is most of a Flask application. The panels are configurable, so a project that only wants request timings and template timings can turn the rest off, and the project is run from the Pallets Ecosystem, the organisation that maintains Flask itself.

Two lines of setup

The example in the README is the whole installation. You import the extension, create the application, set a secret key and pass the app to the extension:

from flask import Flask
from flask_debugtoolbar import DebugToolbarExtension

app = Flask(__name__)
app.config["SECRET_KEY"] = "<replace with a secret key>"

toolbar = DebugToolbarExtension(app)

There is no separate blueprint to register, no middleware to add and no template to include by hand, because the injection into the rendered page is the extension's job. The secret key is required by Flask itself for session handling, and the placeholder in the example is a placeholder, so an application that keeps it in a configuration file should do that instead. The extension is typed, the package declares a Typing :: Typed classifier, and the package requires Python 3.8 or newer and Flask 2.3.0 or newer. The build is flit, with the module name declared as flask_debugtoolbar, and the source lives under src/ with the tests in tests/ and the documentation in docs/.

It appears only in debug mode

The toolbar is automatically injected into Jinja templates when debug mode is enabled, and the run command in the example is the standard Flask development server with the debug flag:

$ flask -A my_app run --debug

That conditional is a safety property rather than a convenience. A debugging overlay that renders request internals into the page is not something to ship, and gating it on debug mode means the default production configuration does not include it, which is the behaviour you want from an extension that is easy to forget about. The example application in the repository, an app.py with a templates directory, exists to show the toolbar in action, and the documentation site carries a recorded example of it. The extension is also useful in a narrower way, since the panels are the same kind of information a Django developer would expect, which is why a port of the Django tool is a reasonable default for a Flask project that wants the Django workflow.

SQL analysis is an opt-in extra

The runtime dependencies are deliberately thin. The package depends on Flask and nothing else, with a version floor of 2.3.0, and everything else is optional. The one extra that exists is sqlalchemy, which pulls in Flask-SQLAlchemy at 3.0 or newer, and that is the switch that enables database related panels in a project that uses that ORM. That is a good design for an extension, since the panel set that needs an ORM should not force the ORM on applications that do not have one, and it keeps the dependency tree of the base install to a single package. The package metadata also lists the license as a file reference, the licence being BSD-3-Clause, and the author as Michael van Tellingen with the maintainers given as the Pallets Ecosystem, which is the arrangement the Pallets community projects use after the original maintainer steps back.

The toolchain is strict in two places

The project configuration is more detailed than the code, and it describes how the maintainers want the project worked on. Mypy is configured in strict mode, targeting Python 3.8, over both the source package and the tests, with error codes shown and pretty output, and there is a specific override that tells mypy to ignore missing imports for sqlparse, which is the optional dependency's helper. Pyright is also configured, with the same Python version, but in basic type checking mode rather than strict, so the two checkers complement each other rather than duplicate. Ruff does the linting with the bugbear, pycodestyle, pyflakes, isort and pyupgrade rule families selected, and it is configured to fix in place and show the fixes. Pytest is configured to treat warnings as errors, which is the setting that catches a deprecation before it becomes a surprise, and coverage is measured with branch coverage enabled over the package and the tests, with source paths mapped so a coverage report from an installed copy lines up with the source tree. The repository also carries a tox.ini, a pre-commit configuration and a Read the Docs configuration.

Community maintenance, and a quiet release history

The project is part of the Pallets Community Ecosystem, and the note about it in the README is explicit about what that means. Pallets is the open source organisation that maintains Flask, and Pallets-Eco enables community maintenance of related projects, with an invitation to reach out on the Pallets Discord server if you are interested in helping maintain it. That is the arrangement to be aware of when evaluating the project, because community maintenance is a different promise from an original author with a large user base behind them. The release history is quiet in the same way. The listed versions are 0.16.0 from 2024-09-28, 0.15.1 from 2024-04-27 and 0.15.0 from 2024-04-24, and the last push to the repository was on 2026-10-05, so the code is being worked on without a new tagged release in a while. The development status in the package metadata says 4, Beta, and the project is BSD-3-Clause licensed with the documentation at flask-debugtoolbar.readthedocs.io.

Editorial conclusion

Flask-DebugToolbar fits a Flask developer who wants request and template diagnostics without a separate profiler process, and the port from django-debug-toolbar means the panel model is the one Django developers already know. It does not fit a production deployment, since the toolbar appears only in debug mode and has no business being enabled there, and it does not fit a team that needs SQL query analysis without opting into the SQLAlchemy extra. Before you add it, set a real secret key rather than the placeholder in the example, check the development status in the package metadata, which reads as beta, and note the release state, where 0.16.0 was published on 2024-09-28 while the last push to the repository was on 2026-10-05.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. pallets-eco/flask-debugtoolbar on GitHub
3. Project website
4. README
5. Releases