Using the Python Debugger pdb

This is a very basic introduction to pdb for debugging in Python. pdb is very easy to use if you know a few of the commands. This short guide will use the following example code: ~/Desktop/add.py Notice that I’ve imported pdb, and I’ve inserted pdb.set_trace() where I want to start debugging my code. All we have to do is run the program:

user@PCname:~$ python ~/Desktop/add.py
> /home/user/Desktop/add.py(10)<module>()
-> a = 2
(Pdb) 

Now we are at the pdb prompt: (Pdb). Let’s try some pdb commands, starting with n (next):

(Pdb) n
> /home/user/Desktop/add.py(11)<module>()
-> b = 3

So now the first line of code has been executed (a = 2) and pdb is showing us that the next line to be executed is line 11 (b = 3). If we just keep pressing n, the entire program will eventually execute. That, however, will not really teach us anything. Let’s try another command: p (print). p will print the value of variables. You just have to tell it which variable to print by entering the name of the variable after the p:

(Pdb) p a
2

You’ll notice that as we have advanced through the program, pdb has been showing us where we are in the program by printing the line number and value of the next line to be executed before returning to the (Pdb) prompt. However, if you still get lost, just use the l (list) command to list the surrounding 11 lines of code with an arrow marking the next line to be executed:

(Pdb) l
  6  	def add(x, y):
  7  	    return x + y
  8  	    
  9  	pdb.set_trace()
 10  	a = 2
 11  ->	b = 3
 12  	c = add(a, b)
 13  	print "a + b = " + str(c)
 14  	
[EOF]

So the next line will define the variable b. Let’s check it out:

(Pdb) n
> /home/user/Desktop/add.py(12)<module>()
-> c = add(a, b)
(Pdb) p b
3

As you can see, the next line will call the add function. If we were to use the n command at this point, we would not get to go through the add function step by step. Instead, the function would execute in full and we would move on to the next line of code (the print line). Usually, I’m using pdb because I can’t figure out what’s wrong with my program, so I like to go through my functions in detail. That’s where the s (step into) command comes in handy. It’s used to step into functions/subroutines:

(Pdb) s
--Call--
> /home/user/Desktop/add.py(6)add()
-> def add(x, y):

Now we’re ready to step through the add function:

(Pdb) n
> /home/user/Desktop/add.py(7)add()
-> return x + y
(Pdb) p x
2
(Pdb) p y
3
(Pdb) n
--Return--
> /home/user/Desktop/add.py(7)add()->5
-> return x + y
(Pdb) n
> /home/user/Desktop/add.py(13)<module>()
-> print "a + b = " + str(c)
(Pdb) p c
5

Above we have stepped through the add function with a brief pause to print the x and y variables. If this were a longer function and we had grown tired of stepping through it, we could have skipped ahead to the end of the function with the r (return) command. Let’s say we think we have identified the source of a bug in our program, and we’d like to see if changing one of the variables fixes the problem. We can simply redefine the variable (or even define a new one) via a standard python command from within pdb. However, we have to ensure that our python command does not begin with one of the pdb commands, or it will be misinterpreted as a pdb command instead. We can tell pdb that we are entering a python command instead of a pdb command by prefixing the command with an exclamation mark:

(Pdb) !b = 4
(Pdb) !c = add(a, b)
(Pdb) p c
6

As you can see, we have redefined the b variable and called the add function again with the new value, so that the resulting c variable contains a different value. Pretty cool, huh? Now let’s say we’re done messing with our program and we just want it to finish executing without having to press n a billion times. For this we’ll use the c (continue) command:

(Pdb) c
a + b = 6
user@PCname:~$

Now the program has executed the last statement and finished. We’re done. However, it’s also handy to know that you can quit the pdb at any time by using the q command, which will kill the program and exit pdb immediately. The h (help) command also comes in handy. It will print all available pdb commands from the (Pdb) prompt. Thanks to Steve Ferg for his similar guide that got me started with pdb.