In all programming exercises, it is difficult to go far and deep without a handy debugger. The built-in debugger, pdb, in Python is a mature and capable one that can help us a lot if you know how to use it. In this tutorial we are going see what the pdb can do for you as well as some of its alternative.

In this tutorial you will learn:

  • What can a debugger do
  • How to control a debugger
  • The limitation of Python’s pdb and its alternatives

Let’s get started.

Python debugging tools
Photo by Thomas Park. Some rights reserved.

Tutorial Overview

This tutorial is in 4 parts, they are

  • The concept of running a debugger
  • Walk-through of using a debugger
  • Debugger in Visual Studio Code
  • Using GDB on a running Python program

The concept of running a debugger

The purpose of a debugger is to provide you a slow motion button to control the flow of a program. It also allow you to freeze the program at certain point of time and examine the state.

The simplest operation under a debugger is to step through the code. That is to run one line of code at a time and wait for your acknowledgment before proceeding into next. The reason we want to run the program in a stop-and-go fashion is to allow us to check the logic and value or verify the algorithm.

For a larger program, we may not want to step through the code from the beginning as it may take a long time before we reached the line that we are interested in. Therefore, debuggers also provide a breakpoint feature that will kick in when a specific line of code is reached. From that point onward, we can step through it line by line.

Walk-through of using a debugger

Let’s see how we can make use of a debugger with an example. The following is the Python code for showing particle swarm optimization in an animation:

The particle swarm optimization is done by executing the update() function a number of times. Each time it runs, we are closer to the optimal solution to the objective function. We are using matplotlib’s FuncAnimation() function instead of a loop to run update(). So we can capture the position of the particles at each iteration.

Assume this program is saved as, to run this program in command line is simply to enter:

and the solution will be print out to the screen and the animation will be saved as PSO.gif. But if we want to run it with the Python debugger, we enter the following in command line:

The -m pdb part is to load the pdb module and let the module to execute the file for you. When you run this command, you will be welcomed with the pdb prompt as follows:

At the prompt, you can type in the debugger commands. To show the list of supported commands, we can use h. And to show the detail of the specific command (such as list), we can use h list:

At the beginning of a debugger session, we start with the first line of the program. Normally a Python program would start with a few lines of import. We can use n to move to the next line, or s to step into a function:

In pdb, the line of code will be printed before the prompt. Usually n command is what we would prefer as it executes that line of code and moves the flow at the same level without drill down deeper. When we are at a line that calls a function (such as line 11 of the above program, that runs z = f(x, y)) we can use s to step into the function. In the above example, we first step into f() function, then another step to execute the computation, and finally, collect the return value from the function to give it back to the line that invoked the function. We see there are multiple s command needed for a function as simple as one line because finding the function from the statement, calling the function, and return each takes one step. We can also see that in the body of the function, we called np.sin() like a function but the debugger’s s command does not go into it. It is because the np.sin() function is not implemented in Python but in C. The pdb does not support compiled code.

If the program is long, it is quite boring to use the n command many times to move to somewhere we are interested. We can use until command with a line number to let the debugger run the program until that line is reached:

A command similar to until is return, which will execute the current function until the point that it is about to return. You can consider that as until with the line number equal to the last line of the current function. The until command is one-off, meaning it will bring you to that line only. If you want to stop at a particular line whenever it is being run, we can make a breakpoint on it. For example, if we are interested in how each iteration of the optimization algorithm moves the solution, we can set a breakpoint right after the update is applied:

After we set a breakpoint with the b command, we can let the debugger run our program until the breakpoint is hit. The c command means to continue until a trigger is met. At any point, we can use bt command to show the traceback to check how we reached here. We can also use the p command to print the variables (or an expression) to check what value they are holding.

Indeed, we can place a breakpoint with a condition, so that it will stop only if the condition is met. The below will impose a condition that the first random number (r1) is greater than 0.5:

Indeed, we can also try to manipulate variables while we are debugging.

In the above, we use l command to list the code around the current statement (identified by the arrow ->). In the listing, we can also see the breakpoint (marked with B) is set at line 40. As we can see the current value of V and r1, we can modify r1 from 0.54 to 0.2 and run the statement on V again by using j (jump) to line 38. And as we see after we execute the statement with n command, the value of V is changed.

If we use a breakpoint and found something unexpected, chances are that it was caused by issues in a different level of the call stack. Debuggers would allow you to navigate to different levels:

In the above, the first bt command gives the call stack when we are at the bottom frame, i.e., the deepest of the call stack. We can see that we are about to execute the statement X = X + V. Then the up command moves our focus to one level up on the call stack, which is the line running update() function (as we see at the line preceded with >). Since our focus is changed, the list command l will print a different fragment of code and the p command can examine a variable in a different scope.

The above covers most of the useful commands in the debugger. If we want to terminate the debugger (which also terminates the program), we can use the q command to quit or hit Ctrl-D if your terminal supports.

Debugger in Visual Studio Code

If you are not very comfortable to run the debugger in command line, you can rely on the debugger from your IDE. Almost always the IDE will provide you some debugging facility. In Visual Studio Code for example, you can launch the debugger in the “Run” menu.

The screen below shows Visual Studio Code at debugging session. The buttons at the center top are correspond to pdb commands continue, next, step, return, restart, and quit respectively. A breakpoint can be created by clicking on the line number, which a red dot will be appeared to identify that. The bonus of using an IDE is that the variables are shown immediately at each debugging step. We can also watch for an express and show the call stack. These are at left side of the screen below.

Using GDB on a running Python program

The pdb from Python is suitable only for programs running from scratch. If we have a program already running but stuck, we cannot use pdb to hook into it to check what’s going on. The Python extension from GDB, however, can do this.

To demonstrate, let’s consider a GUI application. It will wait until user’s action before the program can end. Hence it is a perfect example to see how we can use gdb to hook into a running process. The code below is a “hello world” program using PyQt5 that just create an empty window and waiting for user to close it:

Let’s save this program as and run it using the following in Linux under X window environment:

The final & will make it run in background. Now we can check for its process ID using the ps command:

The ps command will tell you the process ID at the first column. If you have gdb installed with python extension, we can run

and it will bring you into the GDB’s prompt:

GDB is supposed to be a debugger for compiled programs (usually from C or C++). The Python extension allows you to check the code (written in Python) being run by the Python interpreter (which is written in C). It is less feature-rich than the Python’s pdb in terms of handling Python code but useful when you want to need to hook into a running process.

The command supported under GDB are py-list, py-bt, py-up, py-down, and py-print. They are comparable to the same commands in pdb without the py- prefix.

GDB is useful if your Python code uses a library that is compiled from C (such as numpy) and want to investigate how the it runs. It is also useful to learn why your program is frozen by checking the call stack in run time. However, it may be rarely the case that you need to use GDB to debug your machine learning project.

Further Readings

The Python pdb module’s document is at

But pdb is not the only debugger available. Some third-party tools are listed in:

For GDB with Python extension, it is most mature to be used in Linux environment. Please see the following for more details on its usage:

The command interface of pdb is influenced by that of GDB. Hence we can learn the technique of debugging a program in general from the latter. A good primer on how to use a debugger would be


In this tutorial, you discovered the features of Python’s pdb

Specifically, you learned:

  • What can pdb do and how to use it
  • The limitation and alternatives of pdb

In the next post, we will see that pdb is also a Python function that can be called inside a Python program.