Full-screen console debugger for Python


PuDB: a console-based visual debugger for Python

Gitlab Build Status Github Build Status Python Package Index Release Page

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 commands.
  • 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 "!". Or open a command prompt alongside the source-code via "Ctrl-X".
  • PuDB places special emphasis on exception handling. A post-mortem mode makes it easy to retrace a crashing program's last steps.
  • Ability to control the debugger from a separate terminal.
  • IPython integration (see wiki)
  • Should work with Python 3.6 and newer. (Versions 2019.2 and older continue to support Python 2.7.)


PuDB documentation

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

Development Version

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

git clone https://github.com/inducer/pudb.git

You may also browse the code online.

  • Ctrl-x not function to leave console

    Ctrl-x not function to leave console

    When attempting to make local calls in the console, pressing ctrl-x merely prints ^x rather than leaving the console. At this point, the only way out is to kill pudb. An interesting behavior is that this only happens after issuing a command in the console; ctrl-x works fine until then.

    Details: pudb version: 2015.4.1 installed with pip running in osx 10.11.2 in iTerm2, Terminal, and Neovim's terminal mode

    opened by ghost 58
  • A way to un-breakpoint a set_trace() line

    A way to un-breakpoint a set_trace() line

    This sounds kind of odd, let me explain. I usually enter the debugger with an explicit call to set_trace(). Often, once I've hit that line a few times, I no longer need to stop there, but I don't want to restart the process.

    Just as I can manually turn a regular line into a breakpoint with the 'b' command, I would love a way to turn a set_trace() line back into a regular, non-breaking line. The set_trace function would still be called of course, but could examine the calling line to see if it had been marked as non-breaking, and continue.

    opened by nedbat 33
  • Two New Features

    Two New Features

    Hey there. Here are two features I've wanted for a little while (sorry, probably should have put them in separate branches but they're small and you should be able to cherry pick if you don't want both).

    One of them adds support for bpython-urwid (I think maybe I'll experiment later with getting this to run inside pudb's mainloop, since that can open up some possibilities).

    The other adds support for specifying an arbitrary expression to use as the stringifier for each variable.

    opened by Julian 22
  • Add set_continue() function to __init__.py

    Add set_continue() function to __init__.py

    This lets you start the debugger and immediately continue, i.e., it only stops on a previously defined breakpoint.

    Fixes #234.

    Let me know if you would prefer a better name, or just a flag to set_trace().

    opened by asmeurer 22
  • Problems when setting breakpoints

    Problems when setting breakpoints

    When I try to set a breakpoin, I get the errormessage: The breakpoint you just set may be invalid, for the following reason: File failed to compile.

    I can set breakpoint with Set Anyway. After some debugging, the breakpoint(s) disappear.

    Version of pudb is 2017.1, python 2.7.12+ and Ubuntu 16.10.


    opened by enmy211 21
  • running set_trace() multiple times displays stdlib bdb.py

    running set_trace() multiple times displays stdlib bdb.py

    Reproduction steps:

    1. Save below script as foobar.py
    2. python foobar.py foo bar
    3. You'll break at function foo
    4. Defined a breakpoint at foobar.py:11 (the first line of main(): for arg in argv:)
    5. c
    6. You'll be brought to line 11
    7. c
    8. You'll be brought to /usr/lib/python2.6/bdb.py at _ste_stopinfo(), and also see that you now have two breakpoints at foobar.py:11
    9. Pressing s fourteen times eventually brings you to the correct breakpoint in bar()

    The expected behavior is to not display bdb.py, and not create duplicate breakpoints.

    Obviously there are other ways to accomplish the desired debugging session, but in a large, complex code base, it is sometimes extremely convenient to have multiple set_trace lines, which may or may not cause set_trace to be called twice.

    If you can tell me how to induce this error automatically, I can write a unit test for it, at minimum, and likely produce a patch for the bug as well.

    # Script: foobar.py
    def foo():
        import pudb; pudb.set_trace()
        print 'foo'
    def bar():
        import pudb; pudb.set_trace()
        print 'bar'
    def main(argv):
        for arg in argv:
            if arg == 'foo':
            elif arg == 'bar':
    import sys
    opened by bukzor 20
  • don't provoke undefined signal handling

    don't provoke undefined signal handling

    mod_wsgi installs a non-default signal handler for SIGINT.

    The current behavior of pudb utterly clobbers this signal handler and causes undefined behavior (in practice, the process becomes impossible to kill with SIGINT).

    Until pudb has better support for non-default signal handlers in the process-under-test, I've added this small amount of code to detect the situation, throw a warning, and continue without interrupt support.

    The new warning looks like this under apache.

    [Mon Jun 10 18:44:30 2013] [error] /home/buck/trees/theirs/pudb/pudb/__init__.py:166: UserWarning: A non-default handler for signal 2 is already installed (not installed from python). Skipping pudb interrupt support.
    [Mon Jun 10 18:44:30 2013] [error]   % (interrupt_signal, old_handler))

    Then the process continues to work as well as previous versions of pudb.

    In terms of priority, this is driving everyone that has upgraded pudb completely nuts, and the only recourse is to downgrade.

    opened by bukzor 18
  • Add mouse support and a few changes/fix

    Add mouse support and a few changes/fix

    I know I should have asked when I started adding mouse support. So, I will highlight the changes I have made:

    mouse support

    • add
      • class double_press_input_filter for double click,
      • def listen_mouse_event like def listen, and
      • def mouse_event like def keypress for mouse support.
    • change some event handlers because the argument difference of key event and mouse event, e.g. def move_down(w, size, key) to move_down(w, size, *args). Almost all of those handlers I changed don't use key at all.
    • add some mouse event handler, which are not documented in HELP yet.


    • change change_rhs_box sizing method, which cause both above and below the selected sidebox resize, which is strange to me. I changed it so it would only affect the box below.
    • add non_post_mortem_only decorator, just try to reduce few lines.


    • exception when key press on empty variables list.

    It's fine if no one else wants the mouse support; however if it's accepted, but some naming or style/method don't fit into pudb, please let me know I will add additional changes to meet the need.

    The two changes I made, especially first one, might need more input because not everyone likes the sizing method I like as I don't like the current.

    opened by livibetter 16
  • Add -m switch to run as module

    Add -m switch to run as module


    Here is an implementation for the -m module switch (see https://github.com/inducer/pudb/issues/389).

    Does this look good?

    opened by eliasdorneles 15
  • support set breakpoints from CLI parameters.

    support set breakpoints from CLI parameters.

    ipdb can be used like this:

    ipdb -c 'b FileToSetBreakPoint.py:100' launcher.py
    # 100 is line number where breakpoint be set.

    So Should we pass the parameter "-c" to pdb ?

    Then we can use pudb with shell script.

    opened by yuhuihu 1
  • Include text-wrapping abilities

    Include text-wrapping abilities

    While most code is PEP compliant and well within 80 columns, some of it isn't. I was wondering whether PuDB has the ability to wrap code if it exceeds the current width? If not, is this a reasonable feature to include?

    opened by nikhilweee 1
  • pudb will only display in 25x80 text resolution

    pudb will only display in 25x80 text resolution

    Back a few months ago (March/April 2021 time frame) I used to use PUDB debugger, and it would fit itself to the size of my terminal window. Now I am finding it will only display 25 lines by 80 columns. I have tried different $TERM values, but it doesn't change what I get.

    This is a remote connection (ssh to remote system). I have tried this in a "tmux" session as well as a regular ssh session under Gnome-terminal and xterm. Tested with $TERM unset, as well as xterm-256color, xterm, gnome, linux, and screen-256color (tmux automatically sets $TERM=screen).

    I don't have a simplified script to sun as a test, so the only option I have to try this is a full Tempest testcase, and I have to just close the terminal window so that I don't have to wait for the full testcase to run.

    I'm presuming pudb must have a preferred terminal type. I also uninstalled pudb along with it's dependencies and reinstalled.

    opened by rh-jelabarre 4
  • Include contrib folder and pytorch stringifier

    Include contrib folder and pytorch stringifier

    This PR introduces a new contrib folder under pudb for community customization. A stringifier for pytorch is included. Related issue: #475

    Detailed changelog:

    • A module was added under pudb/contrib/stringifiers as place to store custom stringifiers.
    • A stringifier for pytorch tensors and modules is included.
    • An option was added in the settings menu for the user to enable or disable the cotrib content for users that want to stick to the core pudb installation.
    • Changes were made in var_view.py and settings.py to allow for inclusion of the contrib/stringifiers in the configuration menu.

    Signed-off-by: Giorgos Paraskevopoulos [email protected]

    opened by georgepar 1
  • User contributed addons

    User contributed addons


    First of all thank you for this awesome project. I have created a stringifier for integrating pudb + pytorch to debug ML code, and I am wondering if there is a contrib folder / side-project for user contributed themes / stringifiers.

    I would find it very interesting if such a platform was created to allow users to share domain specific customizations.

    opened by georgepar 1
  • Added configurable key bindings

    Added configurable key bindings

    Tried to implement Configurable key bindings https://github.com/inducer/pudb/issues/460

    • currently added Window chooser keys which could be extended later.
    • will add readme entries post initial review if any

    @inducer Pls let me know initial review comments

    opened by cibinmathew 1
  • Should the current active window has its header bar's color changed by default?

    Should the current active window has its header bar's color changed by default?

    Currently, only the title changes color. In the image below, it's hard to tell right away that the Variables window is active. Other tools don't have this problem because they always have a blinking cursor on the screen. Screenshot_20210715_124311

    If we change the color of the whole header, it's much easier. Screenshot_20210715_123831

    Of course the user can do it themselves by creating custom theme and modify the focused_sidebar element but I think this is asking too much.

    opened by qhuy4119 2
  • Fix crash when expanding variables in post-mortem

    Fix crash when expanding variables in post-mortem

    Currently, Debugger.stack will be empty when entering post-mortem, leading to IndexError when user tries to expand variables in the Variables window. This commit fixes that by restoring Debugger.bottom_frame to Debugger.stack.

    fixes #233

    opened by qhuy4119 1
  • Display path of current source file in header bar

    Display path of current source file in header bar

    Currently, the full path of the current source file will be displayed. This usually results in long path. When the path can't be displayed fully in 1 row for whatever reason (the window is resized, not enough space from the beginning,...), after a Ctrl-L (hotkey for redraw screen), it will wrap automatically, creating more rows as needed. Screenshot_20210713_195215

    We have multiple options to resolve this:

    • Leave as is
    • Only display the filename
    • Calculate the length of the string somehow (from shutil.get_terminal_size(), for example)
    • Let user decide in config file
    • Other....

    Let's discuss this

    fixes #170

    opened by qhuy4119 2
  • Feature request: Customizable key bindings using a config file

    Feature request: Customizable key bindings using a config file

    Enable debugger.py to read the key bindings and action mappings from a config file.

    From a quick look, I think below could be modified https://github.com/inducer/pudb/blob/ba31011c8f491bd6c36b59636f93ebb297ccc180/pudb/debugger.py#L2060-L2075

    opened by cibinmathew 1
Dahua Console, access internal debug console and/or other researched functions in Dahua devices.

Dahua Console, access internal debug console and/or other researched functions in Dahua devices.

bashis 92 Jan 5, 2022
pdb++, a drop-in replacement for pdb (the Python debugger)

pdb++, a drop-in replacement for pdb What is it? This module is an extension of the pdb module of the standard library. It is meant to be fully compat

null 845 Jan 13, 2022
Debugger capable of attaching to and injecting code into python processes.

DISCLAIMER: This is not an official google project, this is just something I wrote while at Google. Pyringe What this is Pyringe is a python debugger

Google 1.6k Jan 2, 2022
pdb++, a drop-in replacement for pdb (the Python debugger)

pdb++, a drop-in replacement for pdb What is it? This module is an extension of the pdb module of the standard library. It is meant to be fully compat

null 845 Jan 13, 2022
Graphical Python debugger which lets you easily view the values of all evaluated expressions

birdseye birdseye is a Python debugger which records the values of expressions in a function call and lets you easily view them after the function exi

Alex Hall 1.4k Jan 2, 2022
Voltron is an extensible debugger UI toolkit written in Python.

Voltron is an extensible debugger UI toolkit written in Python. It aims to improve the user experience of various debuggers (LLDB, GDB, VDB an

snare 5.6k Jan 16, 2022
NoPdb: Non-interactive Python Debugger

NoPdb: Non-interactive Python Debugger Installation: pip install nopdb Docs: https://nopdb.readthedocs.io/ NoPdb is a programmatic (non-interactive) d

Ondřej Cífka 44 Dec 16, 2021
Tracing instruction in lldb debugger.Just a python-script for lldb.

lldb-trace Tracing instruction in lldb debugger. just a python-script for lldb. How to use it? Break at an address where you want to begin tracing. Im

null 102 Jan 8, 2022
Visual Interaction with Code - A portable visual debugger for python

VIC Visual Interaction with Code A simple tool for debugging and interacting with running python code. This tool is designed to make it easy to inspec

Nathan Blank 1 Nov 16, 2021
An improbable web debugger through WebSockets

wdb - Web Debugger Description wdb is a full featured web debugger based on a client-server architecture. The wdb server which is responsible of manag

Kozea 1.5k Jan 11, 2022
PINCE is a front-end/reverse engineering tool for the GNU Project Debugger (GDB), focused on games.

PINCE is a front-end/reverse engineering tool for the GNU Project Debugger (GDB), focused on games. However, it can be used for any reverse-engi

Korcan Karaokçu 1.2k Jan 8, 2022
Little helper to run Steam apps under Proton with a GDB debugger

protongdb A small little helper for running games with Proton and debugging with GDB Requirements At least Python 3.5 protontricks pip package and its

Joshie 17 Jan 9, 2022
Arghonaut is an interactive interpreter, visualizer, and debugger for Argh! and Aargh!

Arghonaut Arghonaut is an interactive interpreter, visualizer, and debugger for Argh! and Aargh!, which are Befunge-like esoteric programming language

Aaron Friesen 2 Dec 10, 2021
A simple rubber duck debugger

Rubber Duck Debugger I found myself many times asking a question on StackOverflow or to one of my colleagues just for finding the solution simply by d

null 1 Nov 10, 2021
Hdbg - Historical Debugger

hdbg - Historical Debugger This is in no way a finished product. Do not use this

Fivreld 2 Jan 2, 2022
Middleware that Prints the number of DB queries to the runserver console.

Django Querycount Inspired by this post by David Szotten, this project gives you a middleware that prints DB query counts in Django's runserver consol

Brad Montgomery 308 Dec 21, 2021
Trace any Python program, anywhere!

lptrace lptrace is strace for Python programs. It lets you see in real-time what functions a Python program is running. It's particularly useful to de

Karim Hamidou 681 Jan 9, 2022
Debugging manhole for python applications.

Overview docs tests package Manhole is in-process service that will accept unix domain socket connections and present the stacktraces for all threads

Ionel Cristian Mărieș 319 Jan 2, 2022
(OLD REPO) Line-by-line profiling for Python - Current repo ->

line_profiler and kernprof line_profiler is a module for doing line-by-line profiling of functions. kernprof is a convenient script for running either

Robert Kern 3.6k Jan 11, 2022