Skip to main content

A package which provides an interactive HTML debugger for Pyramid application development

Project description

pyramid_debugtoolbar provides a debug toolbar useful while you’re developing your Pyramid application.

Note that pyramid_debugtoolbar is a blatant rip-off of Michael van Tellingen’s flask-debugtoolbar (which itself was derived from Rob Hudson’s django-debugtoolbar). It also includes a lightly sanded down version of the Werkzeug debugger code by Armin Ronacher and team.


The documentation of the current stable release of pyramid_debugtoolbar is available at


For a demonstration:

  • Clone the pyramid_debugtoolbar trunk.

    $ git clone
  • Create a virtual environment in the workspace.

    $ cd pyramid_debugtoolbar
    $ python3 -m venv env
  • Install the pyramid_debugtoolbar trunk into the virtualenv.

    $ env/bin/pip install -e .
  • Install the pyramid_debugtoolbar/demo package into the virtualenv.

    $ env/bin/pip install -e demo
  • Run the pyramid_debugtoolbar package’s demo/ file using the virtual environment’s Python.

    $ env/bin/python demo/

Visit http://localhost:8080 in a web browser to see a page full of test options.


If you have tox installed, run all tests with:

$ tox

To run only a specific Python environment:

$ tox -e py311

If you don’t have tox installed, you can install the testing requirements, then run the tests.

$ python3 -m venv env
$ env/bin/pip install -e ".[testing]"
$ env/bin/py.test

Building documentation

If you have tox installed, build the docs with:

$ tox -e docs

If you don’t have tox installed, you can install the requirements to build the docs, then build them.

$ env/bin/pip install -e ".[docs]"
$ cd docs
$ make clean html SPHINXBUILD=../env/bin/sphinx-build

4.10 (2022-01-02)

4.9 (2020-11-24)

  • Support Python 3.9.

  • Added a new Session Panel to track ingress and egress changes to a registered ISession interface across a request lifecycle. By default, the panel only operates on accessed sessions via a wrapped loader. Users can activate the Session Panel, via the Toolbar Settings or a per-request cookie, to track the ingress and egress data on all requests.

    • Removed “Session” section from Request Vars Panel

    • Updated Documentation and Screenshots

  • Ensured the Headers panel only operates when a Response object exists, to create better stack traces if other panels encounter errors.

  • utils.dictrepr will now fallback to a string comparison of the keys if a TypeError is encountered, which can occur under Python3.

    • A test was added to check to ensure sorting errors occur under Python3. If the test fails in the future, this workaround may no longer be needed.

  • Updated toolbar javascript to better handle multiple user-activated panels.

    • split and join functions now use the same delimiter.

    • If the browser supports it, use a “set” to de-duplicate active panels.

  • Inline comments on toolbar.js and to alert future developers on the string delimiters and cookie names.

4.8 (2020-10-23)

4.7 (2020-10-22)

4.6.1 (2020-02-10)

4.6 (2020-01-20)

4.5.2 (2020-01-06)

4.5.1 (2019-11-08)

  • Add Python 3.8 support.

  • Fix internal deprecation warnings on Python 3.7.

4.5 (2018-09-09)

  • Drop Python 3.3 support to align with Pyramid and its EOL.

  • Add support for testing on Python 3.7.

  • Add a list of engines to the SQLAlchemy panel if queries come from multiple engines. See

  • When the toolbar intercepts an exception via debugtoolbar.intercept_exc = True and returns the interactive debugger, it will add request.exception and request.exc_info to the request to indicate what exception triggered the response. This helps upstream tweens such as pyramid_retry to possibly retry the requests. See

  • Stop parsing the request.remote_addr value when it contains chain of comma-separated ip-addresses. Reject these values and emit a warning to sanitize the value upstream. See

4.4 (2018-02-19)

4.3.1 (2018-01-28)

4.3 (2017-07-14)

  • The logging panel indicator is now color-coded to indicate the severity of the log messages as well as the number of messages at said level. There may be more messages, but the most severe show up in the annotation.

    This feature also added a new nav_subtitle_style hook to the DebugPanel API for adding a custom CSS class to the subtitle tag.


4.2.1 (2017-06-30)

4.2 (2017-06-21)

This release contains a rewrite of the underlying exception / traceback tracking machinery and fixes regressions caused by the 4.1 release that broke the interactive debugger. See

  • Tracebacks are now tied to the per-request toolbar object one-to-one. A request may have only one traceback. Previously they actually stuck around for the entire lifetime of the app instead of being collected by the max_request_history setting.

  • The routes for exceptions are standardized to look similar to the SQLA AJAX routes. For example, /{request_id}/exception instead of /exception?token=...&tb=... and /{request_id}/exception/execute/{frame_id}?cmd=... instead of /exception?token=...&tb=...&frm=...&cmd=....

  • Fixed the url generation for the traceback panel link at the bottom of the traceback… it was actually empty previously - it got lost somewhere along the way.

  • /favicon.ico is no longer specially handled.. it’s just part of exclude_prefixes like anything else that you want to exclude.

  • request.pdtb_history is available for toolbar requests (mostly AJAX requests or panel rendering).

  • Removed the unused history predicate.

  • URL generation was broken in the debugger.js but that’s fixed now so the execute/source buttons work in tracebacks.

  • Drop the license from LICENSE.txt for the removed ipaddr module in 4.1. See

4.1 (2017-05-30)

4.0.1 (2017-05-09)

4.0 (2017-05-03)

  • The config settings debugtoolbar.panels, debugtoolbar.extra_panels, debugtoolbar.global_panels and debugtoolbar.extra_global_panels now all accept panel names as defined in Thus you may use names such as performance, headers, etc. These settings still support the dotted Python path but it is suggested that panels now support being included via debugtoolbar.includes and config.add_debugtoolbar_panel instead such that they are automatically added to the toolbar. See

  • Add a new config.add_debugtoolbar_panel directive that can be invoked from includeme functions included via the debugtoolbar.includes setting. These panels are automatically added to the default panel list and should become the way to define toolbar panels in the future. See

  • Add a new config.inject_parent_action directive that can be invoked from includeme functions included via the debugtoolbar.includes setting. These actions are invoked on the parent config just before it is created such that actions can inspect / wrap existing config. See

  • Added “sticky” panel functionality to allow a selected panel to persist across pageviews using cookies. If a cookied panel does not have content available for display, the first non-disabled panel will be displayed. If a cookied panel is not enabled on the toolbar, the first non-disabled panel will be displayed AND will become the new default panel. See

  • Added CustomLoggerFactory to javascript, used in the development of PR 272. This javascript factory allows panel developers and maintainers to use verbose console logging during development, partitioned by feature, and silence it for deployment while still leaving the logging lines activated.

  • The toolbar registers a BeforeRender subscriber in your application to monitor the rendering of templates. Previously it was possible that the toolbar would miss rendering information because of the order in which the subscribers were registered. The toolbar now waits until the application is created and then appends a new subscriber that encapsulates the your application’s BeforeRender subscribers. See

  • Remove duplicate id="${panel.dom_id}" tags in history tab html. Only the top-level <li> tag has the id now. See

  • Emit a warning and disable the toolbar if the app is being served by a forking / multiprocess wsgi server that sets environ['wsgi.multiprocess'] to True. This should help avoid confusing issues in certain deployments like gunicorn and uwsgi multiprocess modes. See

  • The toolbar tween is always placed explicitly OVER the pyramid_tm tween.

  • Refactored all debugtoolbar panels to be included using config.add_debugtoolbar_panel and per-panel includeme functions. See

  • Exposed a request.toolbar_panels dictionary which can be used from within DebugPanel.render_content and DebugPanel.render_vars in order to introspect and use the data generated by other panels when rendering the panel. See

  • Support streaming new requests on Microsoft Edge and Internet Explorer 8+ by using a Server-Sent-Events polyfill. See

3.0.5 (2016-11-1)

3.0.4 (2016-07-26)

  • 3.0.3 was a brownbag release missing static assets.

3.0.3 (2016-07-26)

3.0.2 (2016-07-02)

3.0.1 (2016-05-20)

  • Avoid touching request.unauthenticated_userid, request.authenticated_userid and request.effective_principals unless they are accessed by the user in the normal request lifecycle. This avoids some issues where unauthenticated requests could trigger side effects on your authentication policy or access the properties outside of the expected lifecycle of the properties. See

3.0 (2016-04-23)

  • The toolbar is now a completely standalone application running inside the tween. There are several minor incompatibilities and improvements related to this extra isolation:

    1. pyramid_mako and the .dbtmako renderer are no longer included in the parent application (your app).

    2. Panels must be extra careful now that they only render templates inside of the render_vars and render_content functions. These are the only functions in which the request object is for rendering the toolbar panel.

    3. The toolbar will not be affected by any global security policies your application may put in place other than via config.set_debugtoolbar_request_authorization. never run the toolbar in production


  • Updated Bootstrap to v3.3.6, refactored static assets and dropped require.js. Each page now depends on what it needs without extra dependencies included in the debugger pages. See

  • Enabled interactive tablesorting on table columns. See

  • setuptools-git is now required to install the codebase in non-editable mode.

2.5 (2016-04-20)

2.4.2 (2015-10-28)

  • Fix a long-standing bug in which log messages were not rendered until the end of the response. By this time the arguments passed to the logger may no longer be valid (such as SQLAlchemy managed objects) and you would see a DetachedInstanceError. See

2.4.1 (2015-08-12)

2.4 (2015-06-04)

This release changes some details of the panel API, so if you are writing any custom panels for the toolbar please review the changes.

2.3 (2015-01-05)

2.2.2 (2014-11-09)

  • Brownbagged 2.2.1, forgot to include the templates!

2.2.1 (2014-11-09)

2.2 (2014-08-12)

2.1 (2014-05-22)

  • Add new “debugtoolbar.” configuration settings that allow enabling or disabling various Pyramid knobs in a users .ini file. This for instance allows easy enabling/disabling of template reloading for the debugtoolbar.

  • Allow the toolbar to display always, even when the parent application is using a default permission. See

  • Stabilize and document the pyramid_debugtoolbar.panels.DebugPanel API to allow developers to create their own panels.

  • Add new debugtoolbar.extra_panels and debugtoolbar.extra_global_panels configuration settings to make it simpler to support custom panels without overwriting the default panels.

2.0.2 (2014-02-13)

  • Fix breaking bugs when run under Py3k.

2.0.1 (2014-02-12)

  • Fixes a bug in 2.0 expecting pyramid_beaker to be around.

2.0 (2014-02-12)

  • The toolbar has undergone a major refactoring to mitigate the effects of the toolbar’s internal behavior on the application to which it is connected and make it possible to inspect arbitrary requests. It is now available at /_debug_toolbar and can be used to monitor any and all requests serviced by the Pyramid application that it is wrapping, including non-html responses.

    The toolbar will live-update (on conforming browsers via Server Sent Events) when requests come into the Pyramid application, and can be used to debug and inspect multiple requests simultaneously.

1.0.9 (2013-10-20)

  • Use new pyramid_mako configuration directive add_mako_renderer.

1.0.8 (2013-09-09)

  • Depend on pyramid_mako (Mako support will be split out of Pyramid in 1.5+).

1.0.7 (2013-08-29)

1.0.6 (2013-04-17)

  • Packaging release only, no code changes. 1.0.5 was a brownbag release due to missing directories in the tarball.

1.0.5 (2013-04-17)

  • Parse IPs correctly when request.remote_addr is a comma separated list of proxies IPs.

  • If you are also using require.js, the debug toolbar’s version of jQuery will no longer conflict with your application’s version of the library.

  • Use the “n” filter to disable default_filters when including the raw SQL in links, leaving only the “u” filter (URL escaping).

  • Support for per-request authorization of toolbar middleware via config.set_debugtoolbar_request_authorization(callback) where callback accepts request object and returns boolean value whether toolbar is enabled or not.

  • Short term fix for preventing error when converting binary query params to json.

  • Fix sqlalchemy query duration from microseconds to milliseconds.

1.0.4 (2013-01-05)

  • Add a debugtoolbar.excluded_prefixes setting. When a URL path prefix matches one of these prefixes, the toolbar will not be shown on the resulting page.

  • Show the prompt and little text file icons show all the time, instead of only on hover.

  • Do not set max-height on result boxes (which result in nested scroll on the page, which makes it hard to find information quickly).

  • When an expression result is long, do not truncate with an ellipsis, which requires one more click to get at the information I need.

  • Support pip install from the github repository by adding all static files required to install in the package_data Setuptools usually uses Subversion or CVS to tell it what static files it needs to package up for egg distribution, but does not support reading git metadata.

  • The debug toolbar now use a patched version of require.js with a distinct private name that cannot clash with the dojo loader or other incompatible versions of require that may already be loaded on the page. You no longer need to add the toolbar to your own require.js to make it work.

1.0.3 (2012-09-23)

  • The valid_host custom predicate used internally by pyramid_debugtoolbar views didn’t use newer “ipaddr”-based logic. Symptom: some views may have been incorrectly inaccessible if you used a network mask as a “debugtoolbar.hosts” option.

  • The debug console now works with Google App Engine.

  • The debug console now adds a shortcut for accessing the last result through _.

1.0.2 (2012-04-19)

  • Moved the toolbar and debugger javascript files to use requirejs for better dependency loading and module isolation to play better with mutiple library versions. Recurrent problem was with async loading and application specific jquery library where the expected version was overrided by the toolbar one.

    If you are already using requirejs and want the toolbar to load, just add it to your path and module:

      paths: {
        "jquery": "jquery-1.7.2.min",
        "toolbar": "/_debug_toolbar/static/js/toolbar"
    require(["jquery", "toolbar"], function($, toolbar) {
      $(function() {
        // your module

1.0.1 (2012-03-27)

  • If request.remote_addr is None, disable the toolbar.

1.0 (2012-03-17)

  • Don’t URL-quote SQL parameters on SQLAlchemy panel.

  • Allow hostmask values as debugtoolbar.hosts entries (e.g. (2012-02-22)

  • When used with Pyramid 1.3a9+, views, routes, and other registrations made by pyramid_debugtoolbar itself will not show up in the introspectables panel.

0.9.9 (2012-02-19)

  • Try to take advantage of MakoRendererFactoryHelper in Pyramid 1.3a8+. If we can do this, the toolbar templates won’t be effected by normal mako settings. The most visible change is that toolbar mako templates now have a dbtmako extension.

0.9.8 (2012-01-09)

  • Show request headers instead of mistakenly showing environ values in Headers panel under “Request Headers”. This also fixes a potential UnicodeDecodeError.

  • Set content_length on response object when we regenerate app_iter while replacing original content.

0.9.7 (2011-12-09)

  • The performance panel of the debugtoolbar used a variable named function_calls which was not initialised when stats are not collected. This caused a NameError when mako rendered the template with the strict_undefined option.

  • Fix Python 3 compatibility in SQLAlchemy panel.

  • Make SQLAlchemy explain and select work again.

0.9.6 (2011-12-09)

0.9.5 (2011-11-12)

  • Adjust tox setup to test older Pyramid and WebOb branches under 2.5.

  • Convert all templates to Mako.

  • Don’t rely on pyramid.compat.json.

  • Add Tweens toolbar panel.

0.9.4 (2011-09-28)

  • Upgrade to jquery 1.6.4 and tablesorter plugin 2.0.5b

  • Introduced new setting debugtoolbar.button_style. Which can be used to override the default style (top:30px) set by toolbar.css.

  • Compatible with Python 3.2 (requires Pyramid 1.3dev+).

  • Appease settings values that were sensitive to __getattr__ in the settings debug panel (e.g. MongoDB databases). See

0.9.3 (2011-09-12)

  • All debug toolbar panels and underlying views are now always executable by entirely anonymous users, regardless of the default permission that may be in effect (use the NO_PERMISSION_REQUIRED permission for all debugtoolbar views).

  • Toolbar cookie settings name changed (from fldt to p_dt), to avoid messing up folks who use both the flask debugtoolbar and Pyramid’s.

  • Fix IE7 and IE8 renderings of the toolbar.

0.9.2 (2011-09-05)

  • Log an exception body to the debug toolbar logger when an exception happens.

  • Don’t reset the root logger level to NOTSET in the logging panel (changes console logging output to sanity again).

0.9.1 (2011-08-30)

  • The debugtoolbar.intercept_exc setting is now a tri-state setting. It can be one of debug, display or false. debug means show the pretty traceback page with debugging controls. display means show the pretty traceback package but omit the debugging controls. false means don’t show the pretty traceback page. For backwards compatibility purposes, true means debug.

  • A URL is now logged to the console for each exception when debugtoolbar.intercept_exc is debug or display. This URL leads to a rendering of the “pretty” traceback page for an exception. This is useful when the exception was caused by an AJAX or non-human-driven request. This URL is also injected into the pretty traceback page (at the bottom).

  • “Unfixed” indentation of SQL EXPLAIN done in 0.9, it broke the explain page when a column value isn’t a string.

0.9 (2011-08-29)

  • Fixed indentation of SQL EXPLAIN by replacing spaces with HTML spaces.

  • response.charset in some undefined user-reported cases may be None, which would lead to an exception when attempting to render the debug toolbar. In such cases we now assume the charset is UTF-8.

  • Some renderings of the request vars and renderer values would raise an uncaught exception.

0.8 (2011-08-24)

  • Try to cope with braindead Debian Python installs which package the pstats module separately from Python for god only knows what reason. Turn the performance panel off in this case instead of crashing.

0.7 (2011-08-24)

  • Docs-only changes.

0.6 (2011-08-21)

  • Do not register an alias when registering an implicit tween factory (compat with future 1.2 release).

0.5 (2011-08-18)

0.4 (2011-08-18)

  • Change the default value for debugtoolbar.intercept_redirects to false. Rationale: it confuses people when first developing if the application they’re working on has a home page which does a redirection.

0.3 (2011-08-15)

  • Request vars panel would cause a UnicodeDecodeError under some circumstances (see

  • Dynamicize URLs for SQLAlchemy subpanels.

  • Require “pyramid>=1.2dev” for install; the trunk is now “1.2dev” instead of “1.1.1dev”.

  • Requires trunk after 2011-08-14: WSGIHTTPException “prepare” method and alias param to add_tween, BeforeRender event has no “_system” attr.

  • Fix memory leak.

  • HTML HTTP exceptions now are rendered with the debug toolbar div.

  • Added NotFound page to demo app and selenium tests.

0.2 (2011-08-07)

  • Add SQLAlchemy “explain” and “select” pages (available from the SQLALchemy panel next to each query shown in the page).

  • Requires newer Pyramid trunk (checked out on 2011-08-07 or later).

  • Add a link to the SQLAlchemy demo page from the demo app index page.

0.1 (2011-07-30)

  • Initial release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyramid_debugtoolbar-4.10.tar.gz (3.1 MB view hashes)

Uploaded source

Built Distribution

pyramid_debugtoolbar-4.10-py3-none-any.whl (349.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page