breakpoint()

breakpoint(*args, **kwargs)

breakpoint() pauses your program and drops you into a debugging session at the exact line where it’s called. It’s a built-in, so you don’t need to import anything — just drop breakpoint() anywhere in your code.

Signature and Parameters

breakpoint(*args, **kwargs)

breakpoint() accepts any positional (*args) and keyword (**kwargs) arguments and passes them straight through to sys.breakpointhook(). The default sys.breakpointhook() calls pdb.set_trace() with no arguments, so by default breakpoint() ignores any arguments you pass.

If sys.breakpointhook() doesn’t accept the arguments you give breakpoint(), Python raises TypeError.

What It Does

breakpoint() calls sys.breakpointhook(*args, **kwargs). By default, sys.breakpointhook() calls pdb.set_trace(), which opens the standard Python debugger.

def greet(name):
    message = f"Hello, {name}!"
    breakpoint()
    print(message)

greet("World")

Running this:

> /path/to/file.py(4)greet()
-> print(message)
(Pdb) continue
Hello, World!

At the (Pdb) prompt you can inspect variables, step through code, and continue execution.

Configuring the Debugger with PYTHONBREAKPOINT

The PYTHONBREAKPOINT environment variable controls which debugger breakpoint() invokes. It is re-read on every call to sys.breakpointhook(), so you can change it mid-program.

PYTHONBREAKPOINT value	What happens
Not set / ""	Default — calls pdb.set_trace()
0	Disables breakpoints entirely — sys.breakpointhook() returns None immediately
module.function	Imports module and calls module.function(*args, **kwargs)

Disable all breakpoints

PYTHONBREAKPOINT=0 python myapp.py

# myapp.py
breakpoint()  # becomes a no-op — program keeps running

Use a different debugger

PYTHONBREAKPOINT=ipdb.set_trace python myapp.py

# myapp.py
breakpoint()  # drops into ipdb instead of pdb

You can also use remote debuggers:

PYTHONBREAKPOINT=web_pdb.set_trace python myapp.py

Change debugger at runtime

Because PYTHONBREAKPOINT is re-read on each call, you can change it during execution:

import os
os.environ['PYTHONBREAKPOINT'] = 'pdb.set_trace'
breakpoint()  # uses pdb
os.environ['PYTHONBREAKPOINT'] = '0'
breakpoint()  # becomes a no-op

sys.breakpointhook and sys.breakpointhook

sys.breakpointhook() is the function that breakpoint() calls. You can replace it to change the default debugger globally without touching PYTHONBREAKPOINT.

sys.__breakpointhook__ is initialized to the same function as sys.breakpointhook at startup. This means it holds the initial default — pdb.set_trace() — before any library or code overrides sys.breakpointhook. You can use it to reset back to that initial behavior:

import sys

# Somewhere a library overrides the hook
import some_debugging_library

# Reset to default pdb behavior
sys.breakpointhook = sys.__breakpointhook__

breakpoint()  # uses pdb.set_trace() again

Note: if you override sys.breakpointhook() directly, your replacement is responsible for consulting PYTHONBREAKPOINT if it wants to respect that env var.

Gotchas

IDE debuggers ignore PYTHONBREAKPOINT=0. When running under PyCharm, VS Code, or any IDE that attaches its own debugger, sys.breakpointhook is usually already overridden to use the IDE’s debugger. In that case, PYTHONBREAKPOINT=0 has no effect because the override bypasses the env var check entirely.

Arguments don’t reach pdb.set_trace by default. The default hook passes no arguments to pdb.set_trace(). If you need to pass commands to pdb, you must either override sys.breakpointhook() or call pdb.set_trace() directly:

import pdb
pdb.set_trace('continue', hook)  # pass commands as first arg

RuntimeError if sys is unavailable. If sys.breakpointhook is not accessible for some reason, breakpoint() raises RuntimeError. This is extremely rare in normal usage.

PYTHONBREAKPOINT with no dots loads a builtin. PYTHONBREAKPOINT=int imports the built-in int and calls it:

PYTHONBREAKPOINT=int python -c "breakpoint()"
# int() is called with no args, returns 0

See Also

• /tutorials/intermediate-python/debugging-with-pdb/ — step-by-step debugging with pdb.set_trace() and the breakpoint() workflow
• /reference/built-in-functions/input/ — another debugging-related builtin that halts program execution
• pdb — The Python Debugger — the standard debugger behind breakpoint()
• sys.breakpointhook() — the configurable hook that breakpoint() calls