Getting Started With pdb

Debugging in Python With pdb Austin Cepalia 04:14

Now that you know what pdb is, it’s time to get started! You can break into the debugger with just a single line of Python code:

Python
      
import pdb; pdb.set_trace()

When execution reaches this point, the program stops and you’re dropped into the pdb debugger. If you’re using Python 3.7 or later, then you can also use breakpoint() instead. You can automatically enable or disable all of your breakpoint() calls by modifying environment variables.

pdb also supports post-mortem debugging, which will tell Python to drop you into a pdb prompt as soon as an exception is reached. This is useful for when you don’t have write access to a Python script but still want to debug it. Just run your script like this:

Shell
      
$ python3 -m pdb my_script.py

00:00 Breaking into the debugger can be achieved with just a single line of Python code. It’s import pdb; pdb.set_trace(). When execution reaches this point in the program, the program stops and you’re dropped into the pdb debugger. Effectively, this is the same as inserting a breakpoint on the line below where we call set_trace().

00:29 That means that execution will stop right before that line of code is executed.

00:36 If you’re using Python 3.7 or later, there’s an even easier way. Simply calling the breakpoint() function works in the exact same way. That will automatically import pdb and call set_trace() for you.

00:53 The advantage to using the breakpoint() function instead of the set_trace() function is that you can modify its behavior by changing your environment variables.

01:03 This allows you to enable or disable all the breakpoints before your script even runs, instead of having to manually comment all your breakpoint function calls out.

01:15 Finally, pdb supports what’s called post-mortem debugging. This allows you to break into the debugger without modifying the code at all. No breakpoint() function, no set_trace() calls—nothing.

01:29 This is useful for when you want to debug a program that you don’t have write access to. That looks like this. python3 -m pdb and then the script name. Let’s look at an example Python file that uses the set_trace() function to set a breakpoint.

01:49 I’m here in Visual Studio Code, as usual, and I have opened a very short Python script called example1.py. The first line here is going to set a filename equal to the name of the Python file we’re running. Then, I call the set_trace() function, which will set a breakpoint at line number 5.

02:12 Now, I’m going to head over to my Z shell here on the right and I’ll run this Python program how I would normally, ./example1.py.

02:24 And now we’ve got some output. This looks a little bit cryptic, so let me explain what’s going on here. The first line shows an angled bracket (>), followed by the path to the running script, then the line number our breakpoint is on, and then the word <module>().

02:42 Basically, this line is giving us the context of where our breakpoint is located. It’s in example1.py on line 5 at the module level.

02:54 If it were within a function, that function name would be written here instead of module. If you’re curious as to why my path starts with /mnt, that’s because I’m using the Windows Subsystem for Linux, which actually mounts my computer’s Windows partition in the Linux subsystem. Anyways, on the next line, we have an arrow (->), followed by the line the breakpoint is on.

03:21 As you can see, the print() function hasn’t actually been called yet, because execution stops at the breakpoint and won’t start executing that line until we tell it to. But instead of doing that, I want to inspect the value of one of my variables. To do that, I’ll use the p command followed by the variable name.

03:44 When I press Enter, you see the filename is printed within the interactive debugger. If you ever want to quit the interactive debugger, just use q. And ignore that traceback.

03:57 If you’ve been following along, great job. You’ve seen how we can insert a breakpoint into a program and view information about a variable once the breakpoint is hit. Next, let’s dig a little bit deeper and see what else we can do with the p command.

Become a Member to join the conversation.