Install & Compatibility
Where this runs
tested against v2025.1.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.142s · 72.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 0.138s · 73MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
set_trace
✓ from pudb import set_trace
✗ from pudb import set_trace; set_trace()
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)}")
pudb --version
Debug
Known issues
breakingPython 2.7 support was officially dropped after PuDB version 2019.2. Users requiring Python 2.7 must use an older version of the library.fixUpgrade to Python 3.6+ to use current PuDB versions, or pin `pudb<2019.2` for Python 2.7 projects.
affects: 2019.2 and older (for Python 2.7 support)
gotchaStarting 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.fixBe 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.
affects: 2022.1.2 and newer
gotchaRedirecting 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.fixAvoid 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.
affects: All versions
gotchaUsing 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`.fixEnsure `export PYTHONBREAKPOINT="pudb.set_trace"` is set in your shell environment and you are running Python 3.7+.
affects: Python <3.7 or without PYTHONBREAKPOINT set
gotchaWhen 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.fixFollow the documentation's specific steps for setting up PUDB_TTY to ensure correct terminal interaction.
affects: All versions
gotchaThe `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.fixBe aware of this limitation when debugging multi-threaded applications; Ctrl-C might only trigger the debugger in the main thread.
affects: All versions
Upgrade
Version history
2025.1.5latest on PyPI · released Dec 6, 2025
Audit
Dependencies
urwidoptionalPuDB relies on urwid for its terminal user interface. While often installed automatically, manual installation may be required if issues arise.
PythonrequiredRequires Python 3.8 or newer (as per PyPI metadata). Older versions (pre-2019.2) supported Python 2.7.