pudb

Project Overview

pudb is a console-based visual debugger for Python that brings the niceties of modern GUI debuggers into a lightweight, keyboard-friendly terminal package. Source, stack, breakpoints, and variables are visible at once and continuously updated, with an expandable variable tree. It suits debugging directly on servers or remote environments, with themes, a module browser, and post-mortem mode.

A GUI-debugger experience inside the terminal, comfortable breakpoints on servers.

Key Features

• Single-screen overview: source, stack, breakpoints, and variables update live together
• Variable tree: displays expand, collapse, and offer customization
• Keyboard navigation: single-keystroke control with cursor keys and Vi shortcuts
• Breakpoint management: press b on a line and edit breakpoints visually in their window
• Run to cursor: press t to run to the line under the cursor
• Embedded shell: press the exclamation key to open a Python shell in the current environment
• Module browser: press m to view, load, and reload modules
• Post-mortem mode: retrace a crashing program's last steps

Target Audience

• Server-side Python developers
• Remote and SSH workflow users
• Engineers who never leave the terminal
• Scientific computing developers
• Instructors teaching Python debugging

Quick Start

1. Install pudb

pip install pudb

2. Insert a breakpoint in code

import pudb
pudb.set_trace()

3. Run the script and the debugger UI opens in the terminal

4. Key bindings: b sets breakpoints, t runs to line, the exclamation key opens a shell, Ctrl-P switches themes

Core Advantages

• Terminal friendly: a complete visual debugging experience without a GUI
• Quick to learn: keys follow pdb conventions with efficient single-keystroke actions
• Rich themes: bundled themes plus custom theme support

System Requirements

Notes

• Terminal requirement: needs a terminal emulator supporting full-screen text UIs
• Legacy support: only versions 2019.2 and older support Python 2.7
• pytest integration: works as a pytest plugin to drop into debugging on failures