How I use `breakpoint()` to debug Python code

If you didn't have access to a Python IDE like PyCharm how would you debug a Python app?

Before I found breakpoint(), I had to add print statements everywhere and usually I would need to run the app several times in a row just to help me understand what properties certain objects had.

A while ago, my frustration with how slow this workflow was finally reached a critical threshold and motivated me to take some time to learn how to use Python's built-in debugging capabilities.

The breakpoint() function I've been referencing is actually part of a larger set of tools available to Python developers.

It's called pdb and it's extremely useful.

Note: breakpoint() was introduced in Python 3.7. If you are using an earlier version, you'll probably need to use this idiom instead:

import pdb; pdb.set_trace()

Some of you may be confused about the ; here. It's only needed so that it can all be placed on one line.

If you place either of those lines in your code and run it from the command line AND if those lines are executed then you should see everythign stop and a (Pdb) prompt will appear.

You're using pdb now!

important commands

?

The most important command by far is the ? command. If you type ? then press Enter, it will print a list of other commands that you can input while in the Pdb interactive prompt.

Here's what that looks like today:

(Pdb) ?

Documented commands (type help <topic>):
========================================
EOF    cl         down      j         next     return  tbreak     w
a      clear      enable    jump      p        retval  u          whatis
alias  commands   exit      l         pp       run     unalias    where
args   condition  h         list      q        rv      undisplay
b      d          help      ll        quit     s       unt
break  disable    ignore    longlist  r        source  until
bt     display    interact  n         restart  step    up

Miscellaneous help topics:
==========================
exec  pdb

Undocumented commands:
======================
c  cont  continue  debug

c or continue

The next most important command is c or continue. This command is equivalent to resuming the execution of your program.

h or help

Following that, the h or help command is pretty valuable. If you type help <command> and supply any command from the ? menu, it will print some instructions on what the command will do and how to use it. Sometimes it gives example. This is very useful.

In the Pdb interactive prompt, you can also assign variables like normal.

For example, if you want to set up a variable while debugging to store the result of some expression you can do this exactly as you would in your editor:

(Pdb) myvar = 2 + 2
(Pdb) myvar
4

I encourage you to explore some of the other commands that Pdb has to offer. I think you'll find it's easier to get productive with it than you realized and it might help you debug things quicker in situations where you don't have access to an IDE.

I have switched over to using Pdb almost exclusively. One downside of this is that I've had breakpoint() lines committed into my projects which caused weird failures and should be avoided.

I discovered there's a pre-commit hook for preventing exactly this problem and it's called debug-statements. This will stop you from comitting code which contains a breakpoint() call in it. Here's the relevant docs for that: link.