Python Debugging with PDB: A Complete Beginner’s Guide

Debugging is one of the most essential parts of programming. Even the most experienced developers make mistakes, and finding those bugs efficiently can save a lot of time. In Python, one of the most powerful built-in debugging tools is PDB — the Python Debugger. This article will walk you through everything you need to know about debugging Python code using PDB, from basic commands to real-world examples.

What is PDB in Python?

PDB stands for Python Debugger. It is a built-in module in Python that allows you to step through your code, inspect variables, and understand how your program executes line by line. Unlike print-based debugging, PDB lets you interact directly with your code while it’s running — just like a live conversation with your program.

Why Use PDB for Debugging?

• Interactive Control: You can pause your program at any point and check variable values.
• Precise Navigation: Step through your code one line at a time.
• Better Understanding: See how logic flows and identify where things go wrong.
• No Extra Tools Needed: It’s built into Python, no installations required.

How to Start Using PDB

You can activate PDB in multiple ways, but the simplest is by inserting the following line in your code:

import pdb; pdb.set_trace()

This line will pause the program execution at that point and open the PDB console, where you can start entering commands interactively.

Common PDB Commands You Should Know

Command	Description
n (next)	Execute the next line of code within the same function.
s (step)	Step into a function call.
c (continue)	Continue program execution until the next breakpoint.
l (list)	List the source code around the current line.
p (print)	Print the value of an expression or variable.
q (quit)	Quit the debugger and stop the program.

Example: Debugging a Simple Python Program

Let’s say you have a simple Python script that calculates the average of a list of numbers, but you accidentally made a small logic error:

def average(numbers):
    total = 0
    for num in numbers:
        total += num
    avg = total / len(numbers) + 1  # <-- Logical bug here
    return avg

nums = [10, 20, 30]
print("Average:", average(nums))

When you run this, the output is incorrect because of the + 1 in the division. To find and fix this bug, you can use PDB:

import pdb

def average(numbers):
    total = 0
    for num in numbers:
        total += num
    pdb.set_trace()  # Debugging starts here
    avg = total / len(numbers) + 1
    return avg

nums = [10, 20, 30]
print("Average:", average(nums))

When you run this program, Python will stop at the pdb.set_trace() line. Now, you can type commands in the terminal:

(Pdb) p total
60
(Pdb) p len(numbers)
3
(Pdb) p total / len(numbers)
20.0
(Pdb) n
(Pdb) p avg
21.0

Now you can clearly see that the result is incorrect (it should be 20.0). The error comes from the extra + 1 in the code. Remove that, and your program will work as expected!

Setting Breakpoints Without Editing the Code

You can also start debugging from the terminal without adding pdb.set_trace() in your source file. Use the following command:

python -m pdb your_script.py

This command will run your script under the PDB debugger immediately. You can then use all PDB commands interactively from the terminal.

Using Breakpoints for Larger Projects

In larger applications, manually adding pdb.set_trace() might not be efficient. Instead, you can use break commands inside PDB to specify breakpoints by file and line number. For example:

(Pdb) break main.py:25
(Pdb) continue

This will pause execution when line 25 of main.py is reached. You can also list all breakpoints with break and remove them with clear.

Advanced PDB Features

• Conditional Breakpoints: break 30, x > 10 stops only if condition x > 10 is true.
• Post-Mortem Debugging: Inspect errors after a crash using pdb.pm().
• Integration with IDEs: Tools like VS Code, PyCharm, or Jupyter Notebooks allow PDB-based breakpoints visually.

Best Practices When Using PDB

1. Use set_trace() temporarily and remove it before production deployment.
2. Combine PDB with logging for better traceability.
3. Use continue to skip over unimportant lines quickly.
4. Keep your terminal visible when debugging live scripts.

Conclusion

PDB is an essential tool for every Python developer. Whether you’re a beginner learning to find bugs or an experienced coder maintaining complex software, understanding how to use PDB can save you hours of frustration. With commands like step, next, and print, you can take full control of your program and understand its behavior in real-time.

By practicing with PDB, you’ll develop a deeper understanding of how Python executes your code, and debugging will become a powerful part of your development workflow instead of a tedious task.

---

Now that you know how to use Python’s built-in debugger, try it in your next project and experience how efficient debugging can truly be.