{"id":3749,"library":"pudb","title":"PuDB: a console-based visual debugger for Python","description":"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.","status":"active","version":"2025.1.5","language":"en","source_language":"en","source_url":"https://github.com/inducer/pudb","tags":["debugger","cli","tui","development"],"install":[{"cmd":"pip install pudb","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"PuDB relies on urwid for its terminal user interface. While often installed automatically, manual installation may be required if issues arise.","package":"urwid","optional":true},{"reason":"Requires Python 3.8 or newer (as per PyPI metadata). Older versions (pre-2019.2) supported Python 2.7.","package":"Python","optional":false}],"imports":[{"note":"While 'import pudb; pudb.set_trace()' works, 'from pudb import set_trace' is often preferred for conciseness when only set_trace is needed.","wrong":"import pudb; pudb.set_trace()","symbol":"set_trace","correct":"from pudb import set_trace; set_trace()"},{"note":"Requires Python 3.7+ and the PYTHONBREAKPOINT environment variable to be set.","symbol":"breakpoint","correct":"export PYTHONBREAKPOINT=\"pudb.set_trace\"\n# Then in your code:\nbreakpoint()"},{"note":"Used for remote debugging scenarios, typically connecting via telnet.","symbol":"set_trace (remote)","correct":"from pudb.remote import set_trace; set_trace()"}],"quickstart":{"code":"import pudb\n\ndef factorial(n):\n    if n == 0:\n        return 1\n    else:\n        pudb.set_trace() # Execution will pause here\n        return n * factorial(n-1)\n\nprint(f\"Factorial of 5 is: {factorial(5)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.6+ to use current PuDB versions, or pin `pudb<2019.2` for Python 2.7 projects.","message":"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.","severity":"breaking","affected_versions":"2019.2 and older (for Python 2.7 support)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"2022.1.2 and newer"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `export PYTHONBREAKPOINT=\"pudb.set_trace\"` is set in your shell environment and you are running Python 3.7+.","message":"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`.","severity":"gotcha","affected_versions":"Python <3.7 or without PYTHONBREAKPOINT set"},{"fix":"Follow the documentation's specific steps for setting up PUDB_TTY to ensure correct terminal interaction.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of this limitation when debugging multi-threaded applications; Ctrl-C might only trigger the debugger in the main thread.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}