You must have already heard of pdb if you ever had to SSH into a machine to debug a python script. Yet others, who have only coded using PyCharm, Spyder or any other debugger-integrated IDE, might be happily unaware of the existence of python’s built-in debugging module – pdb.

Yes, python has a built-in debugging module which is installed automatically when you setup python in your computer. It is an interactive command line debugger that lets you insert breakpoints and check the state of the program in case of any error.

Invoking pdb

python -m pdb your_script.py

Replace “your_script.py” with the python script that you would like to debug. It is as simple as that.

Okay, let’s write a program to find the HCF of two numbers and name the file hcf.py

Let’s run the program and check the output

Output:

Wait a minute, the HCF of 6 and 9 is supposed to be 3. So, why is it printing 6?

Let’s debug

Let us debug the script and see where did we go wrong:

You can see something similar in your screen. The ‘->’ symbol shows which line is it going to execute next. At the start of the program, it simply shows the first statement of the script. How do we advance?

Enter ‘n‘ (n for Next)

So, now it is going to execute the function get_hcf(). Proceed by pressing ‘n’.

Now, it is on to the next line, where it is going to print the value in result.

What just happened? The program printed ‘3’ and then ended. The –Return– indicates that the program finished executing. Type exit() to exit.

But where did the entire process of calculating HCF go?

We just skipped its debugging. When we press ‘n’, we do not enter the function. Instead, we reach the state where the function has already been executed. To enter the function, we need to step into it. Instead of ‘n’, we need to press ‘s’.

Let’s restart the debugging, and this time, we step into the function.

Press ‘s’ and enter

Did you notice the difference? Now, we are at the start of the method get_hcf(). Go on pressing ‘n’ and notice the number of times the iteration has run.

Program State

We can also check the program state through pdb.

Pause after a few iteration and check the value of ‘hcf’. Press ‘hcf’ and enter.

.....

Depending upon the number of iteration, the value of ‘hcf’ may differ. Run it one more time so that the value of ‘i’ is 4.

Hmm.. The loop should have ended before i=4, since the HCF is 3. So, there must be something wrong here. Oh, right!

Let’s check the value of the condition we have written.

Oh, there it is! We’ve been writing the condition all wrong. Let’s correct it and check the output

That seems correct.

Let’s fix the bug and run the program one more time.

That looks good now!

Adding a breakpoint

Instead of running the program with pdb from the start, we could also place a breakpoint. That way, the program runs as usual and only stops when the breakpoint is reached.

To add a breakpoint, at your desired line, add the following:

import pdb; pdb.set_trace()

Let’s add it to our previous program:

And now, let’s run the program without pdb

Notice that the program executed until the line that the pdb breakpoint was placed. And now, we can debug our way from here 🙂

Useful commands

CommandDescription
nExecute current line. If at the execution of function, executes the function without entering it
sStep into the function. Starts debugging inside of current function.
pPrint value of variable (Example $> p var_name)
ppPretty print value of variable (Example $> pp var_name)
llShows the entire source code of current function with current line marked
hShows available pdb commands
whatisDisplays the object type of variable (Example $> whatis i)
rContinue execution until the current function returns
aPrints argument lists of current function