PuDB

PuDB is a modern, full-screen console debugger for Python that transforms the debugging experience in terminal environments. It provides a visually rich, interactive interface with syntax highlighting, variable inspection, and advanced breakpoint management—all accessible directly from your terminal.

Unlike the standard PDB, PuDB offers a split-pane layout, real-time variable views, and powerful navigation via keyboard shortcuts. Its support for remote debugging and customizable themes makes it a versatile choice for local development, server-side debugging, and educational use.

PuDB excels in scenarios where:

• Real-time visualization of code execution is needed
• Complex data structures require inspection
• Debugging is performed on remote servers or containers
• Interactive learning of Python debugging concepts is desired

Basics

Installation

# Basic installation
pip install pudb

# With additional features
pip install pudb[all]

# Verify installation
python -c "import pudb; print('PuDB installed successfully')"

Starting PuDB

Method 1: Insert Breakpoint in Code

import pudb
pudb.set_trace()  # Execution will pause here with visual interface

Method 2: Run Script with PuDB

python -m pudb script.py

Method 3: Set as Default Debugger

export PYTHONBREAKPOINT=pudb.set_trace

Then use the standard breakpoint() function:

breakpoint()  # Will use PuDB instead of PDB

Method 4: Command Line with Arguments

# Run with arguments
python -m pudb script.py arg1 arg2

# Start debugging from specific line
python -m pudb --continue script.py

PuDB Interface Components

Main Areas

1. Source Code Panel - Shows current code with syntax highlighting and line numbers
2. Variables Panel - Displays local and global variables with expandable structures
3. Stack Panel - Shows call stack with frame navigation
4. Breakpoints Panel - Lists all active breakpoints with location information
5. Command Line - For entering expressions and interactive commands

Interface Layout

┌─────────────────────────────────────────────────────────────┐
│ [Source Code Panel]          │ [Variables Panel]            │
│ Line numbers, syntax         │ Local and global vars        │
│ highlighting, current        │ Expandable data structures   │
│ execution point              │                              │
├─────────────────────────────────────────────────────────────┤
│ [Stack Panel]                │ [Breakpoints Panel]          │
│ Call stack frames            │ Active breakpoints list      │
│ Frame navigation             │ Breakpoint management        │
├─────────────────────────────────────────────────────────────┤
│ [Command Line / Expression Evaluator]                       │
└─────────────────────────────────────────────────────────────┘

PuDB Commands 🔖

# Navigation and flow control
n / next       # Execute next line (don't step into functions)
s / step       # Step into function calls
c / continue   # Continue execution until next breakpoint
r / return     # Continue until current function returns
f / finish     # Continue until current function returns (alias for r)
u / up         # Move up one stack frame
d / down       # Move down one stack frame
t / top        # Go to the top of the call stack
j <line> / jump  # Jump to specific line number
until <line>   # Continue until line number
unt            # Continue until line greater than current

# Breakpoints
b              # Toggle breakpoint at current line
B              # Focus breakpoints panel / Show breakpoints list
H              # Go to current location (jump to current execution line)
m              # Module browser (browse and set breakpoints in modules)

# Information and inspection
l / list       # Show current code
ll / longlist  # Show entire function
w / where      # Show stack trace
bt             # Show stack trace (alias)
p <expr>       # Print expression
pp <expr>      # Pretty-print expression
a / args       # Show function arguments
whatis <expr>  # Show type of expression
source <expr>  # Show source code of object
rv / retval    # Show return value

# Variable commands
!<statement>   # Execute Python statement
interact       # Start interactive interpreter
alias <name> <command>  # Create command alias
unalias <name>          # Remove alias
display <expr>          # Auto-display expression
undisplay <expr>        # Stop auto-displaying

# Interface controls
V              # Toggle variables panel / Focus variables panel
S              # Toggle stack panel / Focus stack panel
C              # Focus code window
B              # Focus breakpoints window
o              # Options dialog / Access configuration settings
?              # Help (show keyboard shortcuts and help)

# Advanced navigation
j/k            # Move down/up in current panel (vim-style)
h/l            # Move left/right between panels
G/g            # Go to end/beginning of file
L              # Go to line / show location
/              # Search in source code
,              # Search previous
.              # Search next
Ctrl-f/Ctrl-b  # Page forward/backward
Ctrl-d/Ctrl-u  # Half page down/up

# System commands
q / quit       # Quit debugger
restart        # Restart program
!              # Open external shell
Ctrl-x         # Built-in interactive shell / Evaluate expression
o              # Show console/output screen
e              # Show exception traceback
Ctrl-E         # Edit current file with $EDITOR
Ctrl-p / Ctrl-P  # Access preferences/themes

# Variable inspection
Enter          # Expand/collapse variable in variables panel
\\             # Expand/collapse all variables recursively

# Special features
<Enter>        # Repeat last command

Basic Debugging Workflow

1. Start Debugging Session

# In your code
import pudb; pudb.set_trace()

# Your code here
def calculate_total(items):
    total = 0
    for item in items:
        total += item['price'] * item['quantity']
    return total

2. Navigate the Interface

1. Examine source code - The main panel shows your code with the current line highlighted
2. Check variables - The variables panel shows current local and global variables
3. Review call stack - The stack panel shows how you got to the current location
4. Manage breakpoints - The breakpoints panel lists all active breakpoints

3. Step Through Code

• Use n to step to the next line
• Use s to step into function calls
• Use c to continue until the next breakpoint
• Use f to finish the current function

4. Inspect Data

• Navigate to the variables panel with V
• Use Enter to expand complex data structures
• Use Ctrl+x to evaluate expressions interactively
• Use / to search through the source code

---

Remote Debugging

pudb.remote enables debugging Python applications that don't have direct terminal access, such as web servers, background processes, GUI applications, or containerized applications. It creates a telnet-based debugging session that you can connect to from any terminal.

Key Benefits

• Debug applications without stdin/stdout access - Web servers, background processes
• Debug containerized applications from host system - Docker, Kubernetes debugging
• Debug web servers without interrupting HTTP responses - Non-blocking debugging
• Debug GUI applications without blocking the interface - Tkinter, PyQt applications
• Debug remote servers over network connections - Production server debugging
• Multiple concurrent debugging sessions - Different ports for different components

Basic Remote Debugging Setup

Method 1: Basic Remote Trace

from pudb.remote import set_trace
set_trace()  # Default: localhost:6899

# Your application code continues here
process_data()

When set_trace() is called, PuDB will:

1. Find a free port and start listening
2. Display a message like: "Please start a telnet session using a command like: telnet 127.0.0.1 6899"
3. Pause execution until a telnet connection is established
4. Provide the full PuDB interface once connected

Connection:

telnet localhost 6899

Method 2: Custom Host and Port

from pudb.remote import set_trace
set_trace(term_size=(120, 40), host='0.0.0.0', port=6900)

# Application logic
run_application()

Advanced Configuration Options

Terminal Size Configuration

from pudb.remote import set_trace

# Method 1: Direct specification
set_trace(term_size=(columns, rows))

# Common terminal sizes
set_trace(term_size=(80, 24))    # Standard
set_trace(term_size=(120, 40))   # Wide
set_trace(term_size=(100, 30))   # Medium

# Method 2: Environment variable
import os
os.environ['PuDB_TERM_SIZE'] = '120,40'
set_trace()  # Will use 120x40

Host and Port Configuration

from pudb.remote import set_trace

# Bind to all interfaces (allows external connections)
set_trace(host='0.0.0.0', port=6899)

# Use random available port
set_trace(port=0)

# Localhost only (secure)
set_trace(host='127.0.0.1', port=6899)

Real-World Use Cases

Web Application Debugging

# Flask application
from flask import Flask, request, jsonify
from pudb.remote import set_trace

app = Flask(__name__)

@app.route('/api/process', methods=['POST'])
def process_data():
    # Debug without blocking HTTP response
    set_trace(port=6899)
    
    data = request.get_json()
    result = complex_processing(data)
    
    return jsonify(result)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Docker Container Debugging

# app.py in Docker container
from pudb.remote import set_trace

def main():
    # Debug inside container, connect from host
    set_trace(host='0.0.0.0', port=6899)
    
    data = "item1,debug_item,item3"
    result = process_application_data(data)
    
    print(f"Application result: {result}")

if __name__ == '__main__':
    main()

Security Considerations

from pudb.remote import set_trace

# SECURE: Only bind to localhost for local debugging
set_trace(host='127.0.0.1', port=6899)

# RECOMMENDED: Use SSH tunneling for remote access
# ssh -L 6899:localhost:6899 user@remote-server

---

Configuration

PuDB Configuration File

PuDB stores configuration in ~/.config/pudb/pudb.cfg:

[pudb]
theme = dark vim
line_numbers = True
variables_weight = 0.5
stack_weight = 0.3
breakpoints_weight = 0.2
sidebar_width = 0.5
wrap_variables = True
display = auto
stringifier = type
current_stack_frame = top

Available Themes

PuDB includes several built-in themes:

• classic - Traditional PuDB colors
• dark vim - Dark theme with vim-inspired colors
• vim - Light vim-inspired theme
• dark - Simple dark color scheme
• light - Simple light color scheme
• monokai - Popular Monokai color scheme
• solarized - Solarized color scheme
• midnight - Very dark theme for low-light environments

Changing Themes

Through Interface

1. Press Ctrl-p or o to open preferences
2. Navigate to theme selection
3. Choose your preferred theme
4. Changes are saved automatically

Environment-Based Configuration

import os
from pudb.remote import set_trace

# Only enable in development environments
if os.getenv('ENVIRONMENT') == 'development':
    set_trace(port=6899)
elif os.getenv('ALLOW_DEBUG_STAGING') == 'true' and os.getenv('ENVIRONMENT') == 'staging':
    # Restricted debugging in staging
    set_trace(host='127.0.0.1', port=6899)
# Never enable in production without explicit override

---

Tutorials

Tutorial 1: Mastering the PuDB Interface

Learn to navigate PuDB's multi-panel interface effectively.

# tutorial_pudb_interface.py
class TaskManager:
    def __init__(self):
        self.tasks = []
        self.completed = []
        self.priority_map = {'low': 1, 'medium': 2, 'high': 3}
    
    def add_task(self, description, priority='medium'):
        import pudb; pudb.set_trace()
        
        task = {
            'id': len(self.tasks) + 1,
            'description': description,
            'priority': priority,
            'priority_score': self.priority_map.get(priority, 2),
            'status': 'pending'
        }
        
        self.tasks.append(task)
        self._sort_tasks()
        return task
    
    def _sort_tasks(self):
        self.tasks.sort(key=lambda x: x['priority_score'], reverse=True)

# Test the interface
manager = TaskManager()
manager.add_task("Learn PuDB interface", "high")

Interface Navigation Tutorial:

1. Source Panel Navigation:

   • Use j/k to move line by line
   • Use G/g to go to end/beginning
   • Use L to jump to specific line number
   • Use / to search, then , and . for prev/next

2. Variables Panel Inspection:

   • Press V to focus on variables panel
   • Use Enter to expand/collapse variables
   • Navigate with arrow keys or j/k
   • Press \\ to expand all variables

3. Stack Panel Analysis:

   • Press S to focus on stack panel
   • Use u/d to move up/down frames
   • Press Enter to jump to frame location

Tutorial 2: Advanced Breakpoint Strategies

# tutorial_advanced_breakpoints.py
import pudb

def process_orders(orders):
    results = []
    
    for i, order in enumerate(orders):
        # Conditional debugging based on order properties
        if order.get('debug') or order.get('amount', 0) > 1000:
            pudb.set_trace()
        
        processed_order = validate_and_process_order(order, i)
        results.append(processed_order)
    
    return results

def validate_and_process_order(order, index):
    # Debug specific order indices
    if index in [3, 7, 12]:  # Debug specific problematic orders
        pudb.set_trace()
    
    # Validation with conditional debugging
    if not order.get('customer_id'):
        pudb.set_trace()  # Debug missing customer ID
        raise ValueError(f"Missing customer_id in order {index}")
    
    if order.get('amount', 0) < 0:
        pudb.set_trace()  # Debug negative amounts
    
    processed = {
        'order_id': order.get('id'),
        'customer_id': order.get('customer_id'),
        'amount': order.get('amount', 0),
        'processed': True,
        'index': index
    }
    
    return processed

Tutorial 3: Debugging Complex Data Structures

# tutorial_complex_objects.py
import pudb

class DataAnalyzer:
    def __init__(self, dataset):
        self.dataset = dataset
        self.statistics = {}
        self.results = []
    
    def analyze(self):
        pudb.set_trace()  # Start debugging
        
        # Complex nested data to inspect
        for category, data in self.dataset.items():
            category_stats = self._analyze_category(category, data)
            self.statistics[category] = category_stats
        
        return self.statistics
    
    def _analyze_category(self, category, data):
        # Debug point for category analysis
        pudb.set_trace()
        
        stats = {
            'count': len(data),
            'values': data,
            'average': sum(data) / len(data) if data else 0,
            'min': min(data) if data else None,
            'max': max(data) if data else None
        }
        
        return stats

# Complex test data
test_data = {
    'sales': [100, 150, 200, 175, 225],
    'expenses': [50, 75, 100, 85, 110],
    'profits': [50, 75, 100, 90, 115],
    'customers': [10, 15, 20, 18, 22]
}

analyzer = DataAnalyzer(test_data)
results = analyzer.analyze()

---

Integration

Docker Integration

Dockerfile Configuration

FROM python:3.9
COPY . /app
WORKDIR /app

# Install debugging tools
RUN pip install pudb

# Expose debugging ports (range for multiple sessions)
EXPOSE 6899-6905

# Set environment for better debugging
ENV PYTHONUNBUFFERED=1
ENV PYTHONIOENCODING=utf-8

CMD ["python", "app.py"]

Docker Compose Configuration

version: '3.8'
services:
  app:
    build: .
    ports:
      - "6899:6899"  # Main debug port
      - "6900:6900"  # Secondary debug port
      - "6901:6901"  # Background tasks
    environment:
      - ENABLE_REMOTE_DEBUG=true
      - DEBUG_PORT=6899
      - DEBUG_COLS=140
      - DEBUG_ROWS=50
    volumes:
      - .:/app  # For live code updates during debugging
    tty: true
    stdin_open: true

IDE Integration

VS Code Configuration

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File with PuDB",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "PYTHONBREAKPOINT": "pudb.set_trace"
            }
        }
    ]
}

Testing Integration

pytest Integration

# conftest.py
import pytest
import os
import pudb

@pytest.fixture(autouse=True)
def debug_on_failure(request):
    """Automatically start debugger on test failure"""
    yield
    
    if request.node.rep_call.failed and os.getenv('PYTEST_DEBUG'):
        pudb.set_trace()

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    """Store test results for debug_on_failure fixture"""
    outcome = yield
    rep = outcome.get_result()
    setattr(item, "rep_" + rep.when, rep)

---

Best Practices

1. Use Specific Ports for Different Components

# Port assignment strategy
PORTS = {
    'web_handler': 6899,
    'background_worker': 6900,
    'database_manager': 6901,
    'api_client': 6902,
    'data_processor': 6903
}

def debug_web_handler():
    set_trace(port=PORTS['web_handler'])

2. Set Appropriate Terminal Size

# Different sizes for different use cases
TERMINAL_SIZES = {
    'minimal': (80, 24),
    'standard': (120, 40),
    'wide': (140, 50),
    'ultra_wide': (160, 60)
}

def debug_complex_data():
    set_trace(term_size=TERMINAL_SIZES['wide'])

3. Use SSH Tunneling for Remote Servers

# Create persistent SSH tunnel
ssh -fN -L 6899:localhost:6899 user@remote-server.com

# Then connect locally
telnet localhost 6899

4. Configure for Production Safety

import os

def safe_debug():
    """Only allow debugging in development environments"""
    if os.getenv('ENVIRONMENT') not in ['development', 'staging']:
        print("Debugging disabled in production")
        return
    
    import pudb; pudb.set_trace()

5. Learn Keyboard Shortcuts

Essential shortcuts:

• n - Next line
• s - Step into
• c - Continue
• b - Toggle breakpoint
• V - Variables panel
• Ctrl+x - Evaluate expression
• ? - Help
• q - Quit

---

Further Reading

Official Documentation

• PuDB Official Documentation
• PuDB GitHub Repository
• PyPI: PuDB Package

Video Resources

• Meet Pudb, a debugger for Python code (YouTube)
• PuDB Intro Screencast (Vimeo)

Community Resources

• Python Debugging Guide
• Real Python Debugging Tutorial

---

PuDB transforms terminal-based debugging with its visual interface and powerful features—master it to debug Python applications more effectively in any environment.