Skip to main content

A full-screen, console-based Python debugger

Project description

PuDB is a full-screen, console-based visual debugger for Python.

Its goal is to provide all the niceties of modern GUI-based debuggers in a more lightweight and keyboard-friendly package. PuDB allows you to debug code right where you write and test it–in a terminal. If you’ve worked with the excellent (but nowadays ancient) DOS-based Turbo Pascal or C tools, PuDB’s UI might look familiar.

Here’s a screenshot:

You may watch a screencast, too.


  • Syntax-highlighted source, the stack, breakpoints and variables are all visible at once and continuously updated. This helps you be more aware of what’s going on in your program. Variable displays can be expanded, collapsed and have various customization options.

  • Simple, keyboard-based navigation using single keystrokes makes debugging quick and easy. PuDB understands cursor-keys and Vi shortcuts for navigation. Other keys are inspired by the corresponding pdb coomands.

  • Use search to find relevant source code, or use “m” to invoke the module browser that shows loaded modules, lets you load new ones and reload existing ones.

  • Breakpoints can be set just by pointing at a source line and hitting “b” and then edited visually in the breakpoints window. Or hit “t” to run to the line under the cursor.

  • Drop to a Python shell in the current environment by pressing “!”.

  • PuDB places special emphasis on exception handling. A post-mortem mode makes it easy to retrace a crashing program’s last steps.

  • IPython integration (see wiki)

  • Should work with Python 2.4 and newer, including Python 3.


Install PuDB using the command:

easy_install pudb

Getting Started

To start debugging, simply insert:

from pudb import set_trace; set_trace()

A shorter alternative to this is:

import pudb; pu.db

Or, if pudb is already imported, just this will suffice:


Insert either of these snippets into the piece of code you want to debug, or run the entire script with:


or, in Python 3:


This is equivalent to:

python -m

which is useful if you want to run PuDB in a version of Python other than the one you most recently installed PuDB with.

Documentation and Support

PuDB has a wiki, where documentation and debugging wisdom are collected.

PuDB also has a mailing list that you may use to submit patches and requests for help. You can also send a pull request to the GitHub repository

Attaching to Running Code

An alternative to using set_trace is to use:

from pudb import set_interrupt_handler; set_interrupt_handler()

at the top of your code. This will set SIGINT (i.e., Ctrl-c) to run set_trace, so that typing Ctrl-c while your code is running will break the code and start debugging. See the docstring of set_interrupt_handler for more information.

Programming PuDB

At the programming language level, PuDB displays the same interface as Python’s built-in pdb module. Just replace pdb with pudb. (One exception: run is called runstatement.)

License and Dependencies

PuDB is distributed under the MIT license. It relies on the following excellent pieces of software:

  • Ian Ward’s urwid console UI library

  • Georg Brandl’s pygments syntax highlighter

Development Version

You may obtain the development version using the Git version control tool.:

git clone

You may also browse the code online.

The repository is also mirrored at GitHub.


Q: I navigated to the Variables/Stack/Breakpoints view. How do I get back to the source view?

A: Press your left arrow key.

Q: Where are breakpoints stored?

A: All PuDB information is stored in a location specified by the XDG Base Directory Specification. Usually, it is ~/.config/pudb. Breakpoints are stored in a file called saved-breakpoints. Also in this location are the shell history from the ! shell (shell-history) and the PuDB settings (pudb.cfg).

Project details

Release history Release notifications | RSS feed

Download files

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

Source Distribution

pudb-2013.3.4.tar.gz (38.2 kB view hashes)

Uploaded Source

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