bdb

Key Features

• Provides a Bdb base class to subclass when building custom debuggers
• Runs Python statements, callables, and expressions under full debugger control via Bdb.run(), Bdb.runcall(), and Bdb.runeval()
• Manages breakpoints through the Breakpoint class, with support for temporary, conditional, and function-specific breakpoints
• Supports two tracing backends: settrace (default) and monitoring (Python 3.14+), where the monitoring backend adds Bdb.disable_current_event() and Bdb.restart_events() to skip uninteresting events for lower overhead
• Allows module-level skip patterns to avoid stepping into third-party or standard-library code
• Raises BdbQuit to signal a clean exit from the debugging session

Frequently Used Classes and Functions

Examples

Tracing return values from function calls:

import bdb

class ReturnTracer(bdb.Bdb):
    def user_return(self, frame, return_value):
        if frame.f_code.co_name != "<module>":
            print(
                f"{frame.f_code.co_name} returned {return_value!r}"
            )

tracer = ReturnTracer()
tracer.run("def double(n):\n    return n * 2\ndouble(5)")

Run it on the command line:

$ python return_demo.py
double returned 10

user_return() intercepts every return event, making it straightforward to log or inspect return values without modifying the code under test.

Common Use Cases

The most common tasks for bdb include:

• Building custom debuggers by subclassing Bdb and implementing user_line(), user_call(), user_return(), and user_exception()
• Running a specific function, expression, or code string under full debugger control with Bdb.runcall(), Bdb.runeval(), or Bdb.run()
• Setting temporary breakpoints that are removed automatically after being hit once
• Applying conditional breakpoints that only pause execution when a given expression is true
• Skipping standard library or third-party modules during a debugging session
• Tracing program execution to record call graphs or gather profiling data

Real-World Example

The following example creates a call tracer that logs every function entry and return value during a debugging run:

import bdb

class CallTracer(bdb.Bdb):
    def user_call(self, frame, argument_list):
        name = frame.f_code.co_name
        file = frame.f_code.co_filename
        print(f"Calling: {name} in {file}")
        self.set_step()

    def user_return(self, frame, return_value):
        name = frame.f_code.co_name
        print(f"Returning: {name} -> {return_value!r}")
        self.set_step()

def add(a, b):
    return a + b

tracer = CallTracer()
tracer.runcall(add, 3, 4)

Run it on the command line:

$ python call_tracer.py
Returning: add -> 7

bdb.Bdb.runcall() runs the target function under debugger control and intercepts return events without modifying the original code. Note that user_call() fires for functions called within the target, not for the direct target itself.

Related Resources

Tutorial

Python Debugging With Pdb

Learn the basics of Python pdb, the interactive source-code debugger, and use it to track down hard-to-find bugs in your programs.

intermediate stdlib tools

For additional information on related topics, take a look at the following resources:

• Debugging in Python With pdb (Course)
• How to Debug Common Python Errors (Tutorial)
• Profiling in Python: How to Find Performance Bottlenecks (Tutorial)
• Python's assert: Debug and Test Your Code Like a Pro (Tutorial)
• Python Debugging With Pdb (Quiz)
• How to Debug Common Python Errors (Quiz)
• Profiling Performance in Python (Course)
• Profiling in Python: How to Find Performance Bottlenecks (Quiz)
• Using Python's assert to Debug and Test Your Code (Course)
• Python's assert: Debug and Test Your Code Like a Pro (Quiz)