Getting started with Python debuggers

What is debugging?#

The goal of debugging is to ensure that your code is free of any errors and issues that may jeopardize the performance of the program. There are two main types of bugs in programming, syntactic errors and semantic errors.

Syntax errors occur as a result of spelling or punctuation errors in the source code, incorrect labeling, failure to define variables and functions, etc.

Here’s an example of a syntax error in Python:

Semantic errors happen when your program can run successfully but behaves incorrectly.

In this example, the code uses the clear() method, which removes all of the animals in the housepets array instead of just the raccoon.

As you can imagine, mistakes like this are pretty common. That’s why virtually all programming languages (and most popular IDEs) support debugging as a standard feature.

What does a debugger do?#

Debuggers are diagnostic tools that allow you to see the execution state and data of a program as it’s running. In other words, you can define the point at which your Python program needs to be stopped and then suspend execution. By suspending your program, you can go in and find information about variable values, the current state of threads, objects currently in the heap, and more.

Don’t rely solely on print()#

It would be remiss of me to write an article about debugging without bringing up print(). Many Python beginners and self-taught Python programmers use print() calls to debug their code. Using print() is a quick and easy way to see if a variable is being assigned its expected value.

However, placing print() calls after every variable to identify where your bugs are is inefficient, and can get unmanageable with larger bodies of code.

Here’s an example of how you might use the print() statement to debug. Try uncommenting the print statements to see where this code went wrong.

How to get started with Python’s pdb module#

What is the pdb module?#

The pdb module is a standard debugger that comes with all versions of Python. So, if you already have Python installed on your machine, you already have pdb. Pdb supports setting conditional breakpoints, single-stepping at the source line level, inspecting stack frames, source code listing, and evaluations of the Python code in the context of the stack frame^[1].

Pdb is a great place to start because it’s a very basic debugger. It’s great for small to medium-sized projects, and you can add different extensions (like pdb++) to make it more useful.

How to start the debugger#

You can start the Python debugger in a few different ways. First, you can import and start it with a single line of code.

import pdb; pdb.set_trace()

Another way is to import the debugger into Python’s Integrated Development and Learning Environment (IDLE) and have it run your module.

You can also call the debugger on the command line. Here’s a mini-tutorial on how you can do just that.

Using the command line:

First, open up a terminal (command line window) and navigate to the program that needs debugging.

Next, import pdb and your module, then execute pdb’s run() method to call the module’s main method.

import pdb
import example.py
pdb.run('example.main()')
<string>(1)<module>()
(Pdb) continue 

This will pull up the debugger’s prompt, where you can type continue or c to proceed with running your program. By continuing, the debugger will keep executing the program until it reaches a breakpoint or the script ends.

You can also start the debugger by executing the following command in your terminal:

python -m pdb example.py

If you’re using Python 3, then use this:

python3 -m pdb example.py

Single-stepping your Python code#

Single-stepping is the process of going through your code one line at a time. You can use the step or s command to do so.

C:\Users\yourname>cd c:\debugging101

c:\debugging101>python -m pdb example.py
> c:\debugging101\example.py(2)<module>()
-> def main():
(Pdb) step
> c:\debugging101\example.py(4)<module>()
-> def doubler(a):
(Pdb) s
> c:\debugging101\example.py(9)<module>()
-> for i in range(1,10):

In lines like c:debugging101\example.py(4)<module>(), the number inside of the parentheses indicates the line where the error is. You can use args or a to print the current argument list to the screen. Another useful command to know is the jump or j command followed by a space and the line number you want to move to. This allows you to skip straight to the line you want.

Setting breakpoints#

A breakpoint is a line in the code where you want to pause execution. You can set breakpoints by calling the break or b command followed by a space and the line number you want to break on. If you want to specify a breakpoint in a different file, you can prefix the line number with a filename and colon.

In addition, you can use the break command without an argument to display all breakpoints in the program. If you use the break command with a function as an argument, it will set a breakpoint at the first executable statement within that function.

If you want to set a temporary breakpoint that gets automatically removed when hit, you can use tbreak.

In this example, we’ve set the breakpoint on line 6.

c:\debugging101>python -m pdb example.py
> c:\debugging101\example.py(4)<module>()
-> def doubler(a):
(Pdb) break 6
Breakpoint 1 at c:\debugging101\example.py:6
(Pdb) c
> c:\debugging101\example.py(6)doubler()
-> result = a*2

From there, you can use the args or a command to print the argument list to the screen.

Handy reference table for pdb commands#

There are some useful debugger commands to know. If any of your variable names are shared with the debugger commands, simply add an exclamation point ! before the variable to distinguish them from each other.

These commands were sourced from the official documentation for the Python Debugger^[2]. Check it out for a more extensive list of commands!