Python breakpoint Function

Last modified April 11, 2025

This comprehensive guide explores Python's breakpoint function, which provides a convenient way to enter the debugger. We'll cover basic usage, configuration, and practical debugging examples.

Basic Definitions

The breakpoint function was introduced in Python 3.7 as a standard way to enter a debugger. It replaces the older import pdb; pdb.set_trace() idiom.

Key characteristics: calls sys.breakpointhook(), uses the PYTHONBREAKPOINT environment variable for configuration, and defaults to pdb.set_trace() if no hook is specified.

Basic Usage

Here's the simplest way to use breakpoint to pause execution and enter the debugger at a specific point in your code.

basic_breakpoint.py

def calculate_sum(a, b):
    result = a + b
    breakpoint()  # Execution pauses here
    return result

print(calculate_sum(5, 7))

When running this code, execution will pause at the breakpoint() call. You'll enter the Python debugger (pdb) interactive prompt.

At the debugger prompt, you can inspect variables (like result), step through code, or continue execution with the c command.

Conditional Breakpoints

You can make breakpoints conditional by wrapping them in an if statement. This example only breaks when a specific condition is met.

conditional.py

def process_data(data):
    for item in data:
        if item > 100:  # Only break for large values
            breakpoint()
        print(f"Processing {item}")

data = [10, 20, 150, 30, 200]
process_data(data)

The breakpoint will only trigger when processing values greater than 100. This helps focus debugging on specific scenarios.

In the debugger, you can inspect the current item value and the loop state. This technique is useful for debugging edge cases.

Configuring the Debugger

You can configure which debugger breakpoint uses by setting the PYTHONBREAKPOINT environment variable. This example shows how to use different debuggers.

configure.py

# To use pdb (default):
# PYTHONBREAKPOINT=pdb.set_trace python script.py

# To use IPython's debugger:
# PYTHONBREAKPOINT=IPython.embed python script.py

# To disable all breakpoints:
# PYTHONBREAKPOINT=0 python script.py

def buggy_function():
    x = 42
    breakpoint()
    return x * 2

buggy_function()

The environment variable controls which debugger is invoked. Setting it to 0 completely disables breakpoints, which is useful for production.

This flexibility allows teams to use their preferred debugger while maintaining consistent breakpoint() calls in the codebase.

Post-Mortem Debugging

breakpoint can be used for post-mortem debugging after an exception occurs. This example shows how to enter the debugger after a crash.

post_mortem.py

def divide(a, b):
    try:
        return a / b
    except Exception:
        breakpoint()  # Debug the exception
        raise

# This will trigger the breakpoint
divide(10, 0)

When the division by zero occurs, execution pauses at the breakpoint inside the except block. You can inspect the exception and program state.

This technique is valuable for understanding why exceptions occur and examining the program state at the moment of failure.

Advanced Usage with sys.breakpointhook

For advanced scenarios, you can customize the breakpoint behavior by modifying sys.breakpointhook. This example shows a custom debugger hook.

custom_hook.py

import sys

def custom_debugger(*args, **kwargs):
    print("Custom debugger activated!")
    print(f"Args: {args}")
    print(f"Kwargs: {kwargs}")
    # Implement your debugger logic here

sys.breakpointhook = custom_debugger

def test_function():
    x = 10
    y = 20
    breakpoint()
    return x + y

test_function()

This replaces the default debugger with a custom function. The function receives the current frame, filename, and line number as arguments.

Advanced users can implement their own debugging interfaces or integrate with external debugging tools using this hook system.

Best Practices

Remove in production: Disable breakpoints via PYTHONBREAKPOINT=0
Use meaningful conditions: Make breakpoints trigger only when needed
Document breakpoints: Add comments explaining why the breakpoint exists
Prefer over pdb.set_trace: Use breakpoint() for modern Python code
Clean up: Remove temporary breakpoints after debugging

Source References

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.

Ebooks