PuDB: a console-based visual debugger for Python

2025.1.5 · active · verified Sat Apr 11

PuDB is a full-screen, console-based visual debugger for Python. It aims to provide the benefits of modern GUI-based debuggers in a lightweight, keyboard-friendly terminal interface. PuDB allows developers to debug code directly in their terminal environment, with features like syntax-highlighted source, stack, breakpoints, and variables all visible simultaneously. The current version is 2025.1.5, and it maintains an active development and release cadence.

Warnings

breaking Python 2.7 support was officially dropped after PuDB version 2019.2. Users requiring Python 2.7 must use an older version of the library.
Fix: Upgrade to Python 3.6+ to use current PuDB versions, or pin `pudb<2019.2` for Python 2.7 projects.
gotcha Starting from `pudb v2022.1.2`, the debugger automatically breaks and jumps directly into the function that raises an unhandled exception. In older versions, it would report the exception at the call site without automatically jumping, allowing users to debug the exception handler directly.
Fix: Be aware of this change in behavior; if you prefer the old style for debugging exception handlers, you might need to manually navigate the stack or consider older versions if this behavior is critical and unconfigurable.
gotcha Redirecting the standard output of a Python script (e.g., `python script.py > log.txt`) can cause PuDB's TUI to display in a small, squished, and often unusable window. This is typically due to the underlying `urwid` library's inability to correctly detect terminal dimensions when output is redirected.
Fix: Avoid redirecting output directly when invoking a script you intend to debug with PuDB. Run the script normally or use separate terminals for debugger UI (via PUDB_TTY) and program output.
gotcha Using the built-in `breakpoint()` function to invoke PuDB requires Python 3.7 or newer and the `PYTHONBREAKPOINT` environment variable set to `pudb.set_trace`. Without this, `breakpoint()` will default to `pdb`.
Fix: Ensure `export PYTHONBREAKPOINT="pudb.set_trace"` is set in your shell environment and you are running Python 3.7+.
gotcha When attempting to debug from a separate terminal using the `PUDB_TTY` environment variable, you must first get the `tty` path (e.g., `/dev/pts/3`) and ensure the target terminal isn't actively reading by running a placeholder command like `perl -MPOSIX -e pause`. Failing to do so can result in unexpected behavior or a non-responsive debugger.
Fix: Follow the documentation's specific steps for setting up PUDB_TTY to ensure correct terminal interaction.
gotcha The `pudb.set_trace()` function installs a SIGINT handler (for Ctrl-C) to break into the debugger. This handler is specific to the main thread and may not function as expected in other threads of your application.
Fix: Be aware of this limitation when debugging multi-threaded applications; Ctrl-C might only trigger the debugger in the main thread.

Install

pip install pudb Install latest version

Imports

set_trace
```
from pudb import set_trace; set_trace()
```
While 'import pudb; pudb.set_trace()' works, 'from pudb import set_trace' is often preferred for conciseness when only set_trace is needed.
breakpoint
```
export PYTHONBREAKPOINT="pudb.set_trace"
# Then in your code:
breakpoint()
```
Requires Python 3.7+ and the PYTHONBREAKPOINT environment variable to be set.
set_trace (remote)
```
from pudb.remote import set_trace; set_trace()
```
Used for remote debugging scenarios, typically connecting via telnet.

Quickstart

This quickstart demonstrates how to embed `pudb` directly into your Python code using `pudb.set_trace()`. When the execution reaches this line, the PuDB interface will launch in your terminal, allowing you to step through the code, inspect variables, and manage breakpoints.

import pudb

def factorial(n):
    if n == 0:
        return 1
    else:
        pudb.set_trace() # Execution will pause here
        return n * factorial(n-1)

print(f"Factorial of 5 is: {factorial(5)}")

view raw JSON →