How to use the Python debugger

The power and flexibility of the Python programming language stem from a strong standard library and a rich ecosystem of third-party software. Python programmers can draw on lots of useful tools, and that extends to debugging, too.

Python programs can be debugged using any of the many Python IDEs with debug capabilities, third-party Python debuggers, or special-purpose tools, but interactive debugging is also built right into the language. You can invoke interactive debugging in a Python program as part of its normal execution.

Here we’ll walk through a quick tour of how to use Python’s built-in interactive debugger, pdb.

Python debugger example

The pdb module is part of the Python standard library, so doesn’t need to be installed separately; it can be invoked straight out of the box. Here is a simple example of using pdb:

import pdb
x=0
while True:
    x+=1
    print ("Current number:", x)
    pdb.set_trace()

In Python 3.7 and later, you can (and should) use the new built-in function breakpoint() instead of pdb.set_trace(). (pdb is imported automatically when you run breakpoint().)

x=0
while True:
    x+=1
    print ("Current number:", x)
    breakpoint()

When you run the above program, you'll see Current number: 1 and then a prompt: (Pdb). This prompt indicates the debugger has kicked in and is waiting for a command to execute in the context of the current stack frame.

Python debugger commands

Here are some of the most commonly used commands in pdb:

p/pp: Print expression

Print (or “pretty print”) the result of some expression. If you run the above program and type p x at the first breakpoint, you should see 1 (the value of x at that point).

c: Continue

Continue with the program’s normal execution until you hit another breakpoint. Type c, then p x at the next breakpoint, and you should see 2 (the value of x after another cycle of the loop).

s: Step forward

Step forward one line in the program. The pdb prompt will reappear after the line has been executed.

l: List source

Print the source code of the program at a specific point in its execution. The current line will appear in the middle of the printout with an arrow next to it.

w: Print stack trace

Displays the entire stack for the program at that moment. This lets you see where the current module is in context with everything else executing.

!: Execute statement

Any valid Python statement can be executed in the context of the module currently running by prefixing it with an exclamation point. For the above example, at the pdb prompt, you could type !x=100 to set x to 100. (Note the absence of spaces in the expression; any spaces would be considered Python syntax indentation.)

Conditional debugging with pdb

Since you can invoke the debugger with just a Python statement, you can have the debugger pop up conditionally — for instance, by using an if/then or try/except block. This is a handy way to deal with problems that pop up when certain conditions arise.

Another way you can perform conditional debugging is by using the commands pdb.run() to evaluate Python statements or pdb.runeval() to evaluate Python expressions:

pdb.run('x+=1')
pdb.runeval('x==0')

When these commands are executed, the expression or statement is evaluated under pdb control. Thus you can dynamically construct expressions or statements at run time and use pdb to see how they shake out.

To learn about other capabilities in pdb, dive into the official Python debugger documentation.