Debugging in Python has had its fair share of issues for developers. A common debugger was the pdb debugger. But, to analyze the session, we would need to do something like:
import pdb
a = None
for i in range(10):
if i == 4:
a = 'Hi'
print('a is set to', a)
elif i == 5:
pdb.set_trace()
Output
a is set to Hi
> d:\user\pdb-tut.py(4)<module>()
-> for i in range(10):
(Pdb) p a
'Hi'
(Pdb)
While you can get the contents of your environment and all the associated variables using pdb.set_trace()
, it often becomes very time consuming to insert this every time there needs to be debugging done.
Furthermore, this does not seem intuitive for all developers to import a module every time debugging needs to be done.
Keeping these concerns in mind, Python 3.7 introduced the breakpoint() method, which does the work of importing pdb
and calling pdb.set_trace()
.
Thus, a call to breakpoint()
will yield a pdb session.
About breakpoint()
The breakpoint()
function calls another method in the sys
module, called sys.breakpointhook()
, which does the entry into the pdb
session.
The signature of the method is: breakpoint(*args, **kwargs)
The positional and keyword arguments are passed to sys.breakpointhook()
, which may raise a TypeError
, if the signatures do not match.
The below example shows how breakpoint()
is used.
a = []
for i in range(10):
a.append(i)
if i == 6:
# Start pdb instance when i = 6
breakpoint()
print(a)
Output
> user/askpython/breakpoint_example.py(3)<module>()
-> for i in range(10):
(Pdb) p a
[0, 1, 2, 3, 4, 5, 6]
(Pdb) n
> user/askpython/breakpoint_example.py(4)<module>()
-> a.append(i)
(Pdb) p a
[0, 1, 2, 3, 4, 5, 6]
(Pdb) n
> user/askpython/breakpoint_example.py(5)<module>()
-> if i == 6:
(Pdb) n
> user/askpython/breakpoint_example.py(3)<module>()
-> for i in range(10):
(Pdb) n
> user/askpython/breakpoint_example.py(4)<module>()
-> a.append(i)
(Pdb) n
> user/askpython/breakpoint_example.py(5)<module>()
-> if i == 6:
(Pdb)
> user/askpython/breakpoint_example.py(3)<module>()
-> for i in range(10):
(Pdb)
> user/askpython/breakpoint_example.py(4)<module>()
-> a.append(i)
(Pdb)
> user/askpython/breakpoint_example.py(5)<module>()
-> if i == 6:
(Pdb)
> user/askpython/breakpoint_example.py(3)<module>()
-> for i in range(10):
(Pdb)
> user/askpython/breakpoint_example.py(8)<module>()
-> print(a)
(Pdb)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
--Return--
The PYTHONBREAKPOINT Environment Variable
The sys.pythonbreakpointhook()
uses the environment variable PYTHONBREAKPOINT
. If this variable is set to 0
or disabled, the pdb
debugger is not used when breakpoint()
is called, thus disabling the debugger.
As a result, we can use this environment variable to switch between debugging modes.
So if there are break-points in the code but you do not want to go into debug mode, simply unset this environment variable when running the Python program.
root@Ubuntu $ PYTHONBREAKPOINT=0 python breakpoint_example.py
Output
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Change debugging sessions
The PYTHONBREAKPOINT
environment variable can be used to debug using various third party debuggers, apart from pdb
.
We can use the variable to set the name of a callable, which starts a third party debugging session, such as web-pdb
and pudb
.
If you want to use them, you can install them using:
pip3 install pudb
pip3 install web-pdb
The below example shows integration with a pudb
debugging session using the breakpoint()
call.
root@Ubuntu $ PYTHONBREAKPOINT=pudb.set_trace python3 breakpoint_example.py
Output

Similarly, a web-pdb
session can be started using the below command. (Notice the underscore instead of the hyphen in the web_pdb.set_trace
command)
root@Ubuntu $ PYTHONBREAKPOINT=web_pdb.set_trace python3 breakpoint_example.py
2019-12-28 14:52:55,398: root - web_console:108 - CRITICAL - Web-PDB: starting web-server on root-pc:5555...
Output (on localhost:5555
)

Conclusion
We learned about Python’s breakpoint()
function used for debugging purposes, and about the PYTHONBREAKPOINT
environment variable, which can be used to start various debugging sessions using other third party debuggers.
References
- Python breakpoint() Documentation
- JournalDev article on breakpoint()