Python breakpoint() Function: A Practical Debugging Guide

A small reporting script can look perfect until it produces the wrong totals for Chicago, Austin, and Seattle. Printing every variable may help, but it quickly makes the terminal noisy and hard to follow.

That is where the Python breakpoint() function saves time. I use it when I need to stop a script at the exact moment data changes, inspect what Python knows, and continue step by step instead of guessing.

What Is the Python breakpoint() Function?

The breakpoint() function pauses a running Python program and opens the built-in debugger. A debugger is a tool that lets you inspect variables, run expressions, move through code, and find the real cause of a problem.

Python introduced breakpoint() in Python 3.7. In a normal terminal setup, it opens the pdb debugger, short for Python Debugger. You do not need to install any package.

customer = "Michael Johnson"
amount = 425

breakpoint()

print(f"Customer: {customer}")
print(f"Amount: ${amount}")

When Python reaches breakpoint(), execution pauses before the print() statements run.

Sample output:

> report.py(6)<module>()
-> print(f"Customer: {customer}")
(Pdb)

You can refer to the screenshot below to see the output.

At the (Pdb) prompt, check the current values:

(Pdb) customer
'Michael Johnson'

(Pdb) amount
425

Type c and press Enter to continue the script.

(Pdb) c
Customer: Michael Johnson
Amount: $425

The function works best when you already know roughly where the issue starts. If you need a refresher on organizing code, see this guide on how to define a function in Python.

Pro Tip: I have found that one well-placed breakpoint() beats ten temporary print() statements. Put it just before the line that produces the unexpected result.

Why Use Python breakpoint() Instead of print()?

A print() statement shows one value at one moment. The Python breakpoint() function gives you an interactive session where you can inspect several values and test expressions before moving forward.

Consider a sales-tax calculation script. The result looks wrong for a customer in Dallas.

customer = {
    "name": "Emily Davis",
    "city": "Dallas",
    "subtotal": 120.00,
    "tax_rate": 0.0825
}

tax = customer["subtotal"] * customer["tax_rate"]

breakpoint()

total = customer["subtotal"] + tax

print(f"Invoice total for {customer['name']}: ${total:.2f}")

Sample output before continuing:

> invoice.py(11)<module>()
-> total = customer["subtotal"] + tax
(Pdb) customer
{'name': 'Emily Davis', 'city': 'Dallas', 'subtotal': 120.0, 'tax_rate': 0.0825}

(Pdb) tax
9.9

(Pdb) customer["subtotal"] + tax
129.9

You can refer to the screenshot below to see the output.

Now you can confirm whether the subtotal, tax rate, and tax calculation are correct. Type c to continue.

(Pdb) c
Invoice total for Emily Davis: $129.90

For simple conversions and cleanup tasks, learning how to convert a string to a float in Python also prevents many calculation bugs before debugging starts.

How to Use Python breakpoint()

The basic workflow is simple:

1. Add breakpoint() before or after the suspicious line.
2. Run the script from your terminal.
3. Inspect variables at the (Pdb) prompt.
4. Move through the code.
5. Continue or quit the program.

Save this example as monthly_report.py.

sales_records = [
    {"rep": "James Wilson", "region": "New York", "sales": 1400},
    {"rep": "Olivia Brown", "region": "Boston", "sales": 1850},
    {"rep": "William Miller", "region": "Miami", "sales": 975}
]

total_sales = 0

for record in sales_records:
    total_sales += record["sales"]

    breakpoint()

print(f"Monthly sales total: ${total_sales}")

Run it with this command:

python monthly_report.py

The debugger stops during the first loop pass.

> monthly_report.py(10)<module>()
-> for record in sales_records:
(Pdb) record
{'rep': 'James Wilson', 'region': 'New York', 'sales': 1400}

(Pdb) total_sales
1400

Type n to run the next line without entering another function.

(Pdb) n
> monthly_report.py(8)<module>()
-> for record in sales_records:

Type c when you finish checking values.

(Pdb) c
Monthly sales total: $4225

This approach is especially useful inside loops. If your script processes lists from a CSV export, first understand how to read large CSV files in Python so you can place breakpoints where records first enter your workflow.

Useful breakpoint() Debugger Commands

When breakpoint() pauses execution, Python displays the (Pdb) prompt. These commands handle most everyday debugging tasks.

The p command is useful when you want a clear expression rather than typing a variable name alone.

employee = {
    "name": "Sarah Martinez",
    "department": "Operations",
    "hours_worked": 38,
    "hourly_rate": 32
}

weekly_pay = employee["hours_worked"] * employee["hourly_rate"]

breakpoint()

print(f"Weekly pay: ${weekly_pay}")

Sample debugger session:

> payroll.py(11)<module>()
-> print(f"Weekly pay: ${weekly_pay}")
(Pdb) p employee["name"]
'Sarah Martinez'

(Pdb) p weekly_pay
1216

(Pdb) c
Weekly pay: $1216

Use pp when you work with nested JSON-like data. It formats long dictionaries and lists more clearly. You may also find this article helpful when working with structured records: how to convert a JSON string to a dictionary.

Pro Tip: In my experience, p and n solve most debugging jobs. Learn those first, then use s only when you need to inspect a function’s internal logic.

Use breakpoint() Inside a Function

The Python breakpoint() function becomes even more valuable when a function receives unexpected input. You can pause inside the function and inspect local variables before it returns a result.

This example calculates a discount for an online order in Denver.

def calculate_discount(order_total, member_level):
    discount_rate = 0

    if member_level == "gold":
        discount_rate = 0.15
    elif member_level == "silver":
        discount_rate = 0.10

    breakpoint()

    discount_amount = order_total * discount_rate
    return discount_amount


customer_name = "Robert Taylor"
discount = calculate_discount(250, "gold")

print(f"Discount for {customer_name}: ${discount:.2f}")

Sample debugger session:

> discounts.py(10)calculate_discount()
-> discount_amount = order_total * discount_rate
(Pdb) p order_total
250

(Pdb) p member_level
'gold'

(Pdb) p discount_rate
0.15

(Pdb) c
Discount for Robert Taylor: $37.50

The debugger shows values that belong to the current function scope. Scope means the part of a program where a variable exists and remains available. This makes breakpoint() much more useful than printing values outside a function.

If functions still feel unclear, review how to call a function in Python and how to return multiple values from Python functions.

Step Into a Function with breakpoint()

Sometimes the main script looks correct, but a helper function changes data incorrectly. Put breakpoint() before the function call, then use s to step into it.

def format_customer_name(first_name, last_name):
    return f"{last_name}, {first_name}"


first_name = "Daniel"
last_name = "Anderson"

breakpoint()

formatted_name = format_customer_name(first_name, last_name)

print(f"Customer record: {formatted_name}")

Sample debugger session:

> customer.py(8)<module>()
-> formatted_name = format_customer_name(first_name, last_name)
(Pdb) s
--Call--
> customer.py(1)format_customer_name()
-> def format_customer_name(first_name, last_name):
(Pdb) n
> customer.py(2)format_customer_name()
-> return f"{last_name}, {first_name}"
(Pdb) p first_name
'Daniel'
(Pdb) p last_name
'Anderson'
(Pdb) c
Customer record: Anderson, Daniel

Use s carefully. If a function calls many other functions, stepping into every one can become slow and confusing. Use n when you trust the function, and use s when you suspect the function itself.

Debug a Data Processing Script

A practical Python automation script often cleans raw data before creating a report. Here, one record includes a missing amount that would break the calculation.

orders = [
    {"order_id": "US-1001", "customer": "Ava Thompson", "amount": "89.50"},
    {"order_id": "US-1002", "customer": "Noah Harris", "amount": ""},
    {"order_id": "US-1003", "customer": "Mia Clark", "amount": "145.00"}
]

total_amount = 0

for order in orders:
    breakpoint()

    amount = float(order["amount"])
    total_amount += amount

print(f"Total order value: ${total_amount:.2f}")

The first record works. At the second breakpoint, inspect the data before Python raises an error.

Sample debugger session:

> orders.py(10)<module>()
-> amount = float(order["amount"])
(Pdb) p order
{'order_id': 'US-1002', 'customer': 'Noah Harris', 'amount': ''}

(Pdb) p order["amount"]
''

The empty string causes a ValueError because Python cannot convert it into a number. Fix the code by validating the value before calling float().

orders = [
    {"order_id": "US-1001", "customer": "Ava Thompson", "amount": "89.50"},
    {"order_id": "US-1002", "customer": "Noah Harris", "amount": ""},
    {"order_id": "US-1003", "customer": "Mia Clark", "amount": "145.00"}
]

total_amount = 0

for order in orders:
    raw_amount = order["amount"]

    if not raw_amount:
        print(f"Skipping {order['order_id']}: missing amount")
        continue

    amount = float(raw_amount)
    total_amount += amount

print(f"Total order value: ${total_amount:.2f}")

Sample output:

Skipping US-1002: missing amount
Total order value: $234.50

This is a useful example of exception handling prevention. Validate expected bad data before it reaches a conversion or calculation. For cases where failures still need handling, see how to catch multiple exceptions in Python.

Disable breakpoint() When Needed

Python lets you disable all breakpoint() calls through the PYTHONBREAKPOINT environment variable. This helps when you want to run a script without editing every debugging line.

On Windows Command Prompt:

set PYTHONBREAKPOINT=0
python monthly_report.py

On macOS or Linux:

PYTHONBREAKPOINT=0 python monthly_report.py

Sample output:

Monthly sales total: $4225

The script skips every breakpoint() call and runs normally. This is handy for a temporary test, but remove breakpoints before committing code or deploying an automation script.

Things to Keep in Mind

• Use Python 3.7 or later: The built-in breakpoint() function does not exist in older Python versions. Check your installed version before relying on it.
• Do not leave breakpoints in production: A breakpoint pauses execution and may stop a scheduled job, web request, or server process.
• Inspect sensitive values carefully: Debuggers can display passwords, API tokens, customer details, and financial data. Avoid sharing terminal logs with exposed secrets.
• Place breakpoints near the suspected issue: A breakpoint inside a large loop may pause hundreds of times and slow down your investigation.
• Use q when stuck: The q command exits the debugger immediately and stops the running program.
• Remove temporary debugging code: Keep your final scripts clean. Use proper logging for long-term monitoring instead of permanent breakpoints.

Frequently Asked Questions

The Python breakpoint() function gives you a fast, built-in way to pause scripts, inspect data, and trace logic errors in real time. Start with one breakpoint near the incorrect result, then expand your checks only when the data points to a deeper issue. I hope you found this practical debugging guide helpful.

You May Also Like

• How to use Python variables
• How to use the Python input function
• How to check if a file exists in Python
• How to create a CSV file in Python
• How to use virtual environments in Python

Bijay Kumar

Bijay Kumar is an experienced Python and AI professional who enjoys helping developers learn modern technologies through practical tutorials and examples. His expertise includes Python development, Machine Learning, Artificial Intelligence, automation, and data analysis using libraries like Pandas, NumPy, TensorFlow, Matplotlib, SciPy, and Scikit-Learn. At PythonGuides.com, he shares in-depth guides designed for both beginners and experienced developers. More about us.

enjoysharepoint.com/