Learn Simple Python Debugging with Pdb

Estimated Read Time: 5 minute(s)
Common Topics: line, breakpoint, pdb, command, set

I’m pretty new to Python, so I was looking around for some debugging tools. At first, I dismissed Pdb (Python debugger) as being too primitive, but after seeing a blog post about using Pdb, I decided that I should give it a try.

To get started with Pdb

  1. import the pdb module
  2. insert a call to the set_trace() method

Here is a simple Python example that calculates and displays a few points on a line. The program is not very interesting and serves only as a vehicle to talk about debugging.

import pdb

def fun(x):
    return 3 * x + 1

for x in range(2, 9):
    y = fun(x)
    print(“(x,y) = (“, x, ” ,”, y, “)”)

When I run the code above (, execution stops at the break-point I set just before the start of the for loop. The line that is shown — -> for x in range(2, 9):  — is the next line to be executed.

Following that line is the Pdb prompt, (Pdb)


We’re now ready to enter some commands. Some of the commands that I’ve found most useful are these:
l (lowercase L) or list – list eleven lines of code around the current position
ll (lowercase L’s) or longlist – list all source code for the current function or frame

Most of the Pdb commands have short forms. To see all of the Pdb commands, type h or help at the Pdb prompt. For help on an individual command, type h or help, followed by the command.

Here is the result of typing l (ell) at the Pdb prompt:


Pressing n or typing next takes us to the next line of code. Pressing n again takes us to the print() statement at the end of the loop body.

Another command, s or step, is similar to n (or next), but will step into a function call rather than stepping over it as s does.

In the next screenshot, the current line is the print statement at the end of the loop body.


An important feature of any debugger is the ability to display the value of a variable. This we can do with the p (or print) command. In the screenshot above, the current line is the print statement, which means it is the next statement to execute. The previous statement, “y = fun(x)” has been executed, so we can see the value of y and x as shown below.


In the screenshot above, we can see that p y results in a value of 7, and p x results in a value of  2.

In summary:

To use Pdb to debug a Python script:

  1. Import the pdb module, with a line near the top of your script.
    import pdb
  2. Call the Pdb method, set_trace().
    Place the call to this method where you want execution to stop.
  3. Get your bearings with l (or list) or ll (or longlist).
  4. Move through your code with n (or next) or s (or step).
  5. Display a value using p <var>, where <var> is the name of the variable or expression you want to display.
  6. For a list of all Pdb commands, type h or help. For help with a specific Pdb command, type h followed by the command, e.g., h break or more simply h b.

Part 2: Breakpoints

Let’s look at another important capability of debuggers: breakpoints. When you set a breakpoint in a program, the debugger executes all of the code up to the breakpoint and then halts. This allows you to inspect variables at that point in the program.
To set a breakpoint, use the Pdb command b or break, followed by the line where you want the breakpoint. It’s helpful to press l (lowercase L) or ll to list (or longlist) your program code with line numbers, as I have done in the following screenshot. The l and ll commands were discussed in the previous Insight article. In this screenshot, the command b 8 means that I’m setting a breakpoint at line 8.
Instead of single-stepping through the code using n or s (next or step) as I did in the previous article, we can use the c (or cont or continue) command to execute code until we reach a breakpoint. The next screenshot shows the result of pressing c — execution stops at the line with y = fun(x)  on line 8, which is where I set the breakpoint.
Pressing c again causes the print() statement to execute, and then starts another iteration of the for loop. Execution stops for the second time at line 8.
You can also set a breakpoint to be triggered conditionally, by adding a logical condition after the line number. I’m going to clear (cl or clear) the breakpoint I set at line 8, using the command cl 1. This was the first breakpoint I set, so its number is 1. Then I’m going to set a new breakpoint inside the function fun(), but only after the expression to be returned is larger than 20.
To do this I use the command b 4, 3 * x + 1 > 20. This command means, “set a breakpoint at line 4, and trigger it when 3 * x + 1 is larger than 20.” Note that you must use a comma between the line number (4) and the logical expression 3 * x + 1 > 20.
After setting the breakpoint and the logical condition, I’ll press c to continue execution until the breakpoint is hit. As you can see in the following screenshot, my program has processed x values of 2, 3, 4, 5, and 6, and has stopped inside the fun() function when x is 7, and 3 * x + 1 is 21, the first value that was larger than 20.

In summary:

  1. Set a breakpoint by typing b or break, followed by the line number at which to set the breakpoint.
  2. Clear a breakpoint by typing cl or clear, and the number (not the line number) of the breakpoint.
  3. Set a conditional breakpoint by typing b (or break), followed by the line number, followed by a comma, and then the logical condition.
  4. As already mentioned, typing h (or help) at the Pdb prompt lists all of the commands, and typing h followed by a specific command gets you to help for that command.

Click For Forums Comments

6 replies
  1. BOAS says:

    Hi Mark,Python has been the language of choice on my physics course, so i'm interested in posts such as these.However, I cannot view the pictures you have uploaded, except for the first one. I'm bringing this to your attention in case anyone else has this problem. (Chrome on OSX if that is useful).Thanks!

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply