In Python 3.7 and newer, breakpoint() stops your program at that line and opens the debugger, by default pdb. There you can inspect variables (p total), step to the next line (n), continue (c), or quit (q). It replaces the older import pdb; pdb.set_trace().
What it actually does is call sys.breakpointhook(). The PYTHONBREAKPOINT environment variable controls that hook: 0 disables every breakpoint, and a dotted name such as ipdb.set_trace chooses a different debugger. The examples below use these controls so they run without stopping.
breakpoint() is a built-in function: it lives in the builtins module, so it is always available without an import. Added in Python 3.7.
Syntax
Put it on the line where you want to stop.
python
def total_price(items):
total = sum(items)
breakpoint() # pdb opens here when run normally
return total
Call
What it does
breakpoint()
Opens pdb at this line.
PYTHONBREAKPOINT=0
Environment setting that turns breakpoints off.
sys.breakpointhook = f
Calls f() instead of the debugger.
breakpoint(*args)
Arguments are passed on to the hook.
Remove breakpoints before committing code, or run tests with PYTHONBREAKPOINT=0 so a forgotten one cannot hang them.
Library declarations
python
breakpoint(*args, **kws)
# calls sys.breakpointhook(*args, **kws); added in Python 3.7
Parameters
Parameter
Description
*args, **kws
Optional. Passed unchanged to sys.breakpointhook(); the default pdb hook ignores them.
Return Value
Return Value
Description
any
Whatever the hook returns; normally None.
Python Examples
Example 1 — Replace the Debugger with a Custom Hook
Point sys.breakpointhook at your own function so every breakpoint just logs a message.
python
import sys
def log_hook(*args, **kwargs):
print("breakpoint reached (custom hook, no debugger)")
sys.breakpointhook = log_hook
total = 0
for n in [3, 4]:
total += n
breakpoint()
print("total:", total)
Output
breakpoint reached (custom hook, no debugger)
breakpoint reached (custom hook, no debugger)
total: 7
How It Works
A replaceable hook.breakpoint() calls whatever function is stored in sys.breakpointhook.
No pause. The custom hook prints and returns, so the loop continues.
Once per call. The loop runs twice, so the message appears twice.
Restore the default.sys.__breakpointhook__ holds the original hook if you need pdb again.
Example 2 — Turn Breakpoints Off with PYTHONBREAKPOINT=0
Set the environment variable from inside the script and watch breakpoint() do nothing.
python
import os
os.environ["PYTHONBREAKPOINT"] = "0"
print("before")
breakpoint()
print("after: breakpoint() was skipped")
Output
before
after: breakpoint() was skipped
How It Works
Checked on every call. The default hook reads PYTHONBREAKPOINT each time a breakpoint is hit.
Zero means off. With the value "0", the call returns immediately.
Usually set outside. In practice you set it in the shell, for example PYTHONBREAKPOINT=0 python app.py.
Safe for automation. Test runners and servers can disable stray breakpoints this way.
Example 3 — Send Breakpoints to Another Callable
Point PYTHONBREAKPOINT at builtins.print and pass arguments through breakpoint().
python
import os
os.environ["PYTHONBREAKPOINT"] = "builtins.print"
for step in range(1, 3):
breakpoint("checkpoint", step)
os.environ["PYTHONBREAKPOINT"] = "0"
breakpoint()
print("done")
Output
checkpoint 1
checkpoint 2
done
How It Works
Dotted name. The default hook imports builtins and calls its print instead of pdb.