How To Use the Python Debugger

Introduction

Debugging is the process of locating and fixing problems that cause a program to behave incorrectly. The built-in Python debugger (pdb) gives developers an interactive environment for tracing execution, inspecting state, and setting breakpoints when debugging Python code.

Prerequisites

To follow the examples below you need Python 3 installed and a terminal or command prompt where you can run Python scripts. Familiarity with basic Python constructs (functions, lists, loops) will help when you step through code with the python debugger.

Quick start: run a script with pdb

The simplest way to start the command-line debugger is to run a module with the -m flag. For example:

$ python -m pdb looping.py

This launches pdb and stops at the first executable line, giving you an interactive prompt where you can enter debugger commands.

Example program

Here is a short example you can use to practice stepping through code and setting breakpoints.

# looping.py
num_list = [500, 600, 700]
alpha_list = ['x', 'y', 'z']

def nested_loop():
    for number in num_list:
        print(number)
        for letter in alpha_list:
            print(letter)

if __name__ == '__main__':
    nested_loop()

Move through code: list, step, next

While in the pdb prompt you’ll often use list, step and next to explore execution. Use list to show source around the current line; step (s) enters called functions and stops at the next possible line; next (n) runs the current line and stops at the next line in the same frame. This distinction (pdb step vs next) matters when you want to step into functions versus skipping over them.

Inspecting values

To inspect variables and expressions, use the print command or pretty-print with pp. These commands are essential when you're learning how to use the python debugger and want to see the runtime state.

(Pdb) pp num_list
[500, 600, 700]

Breakpoints and conditional breakpoints

Breakpoints let you pause execution at a specific file and line or at a function. Set a breakpoint by specifying either a filename:line or a function name. You can also set conditional breakpoints so execution stops only when an expression is true.

(Pdb) b looping.py:7
Breakpoint 1 at looping.py:7

(Pdb) b nested_loop
Breakpoint 2 at looping.py:5

(Pdb) b looping.py:7, number > 500
Breakpoint 3 at looping.py:7  # stop only if number > 500

Use clear to delete breakpoints, disable/enable to toggle them, ignore to skip a breakpoint a number of times, and tbreak to create a temporary breakpoint that removes itself after it is hit.

Integrating pdb into programs

Instead of launching the debugger from the command line, you can embed a trace point inside your code with pdb.set_trace(). This is useful for how to debug python code with pdb when you want the debugger to start at a particular location without externally setting breakpoints.

import pdb

# ...
    print(number)
    pdb.set_trace()  # python pdb set_trace example
    for letter in alpha_list:
        print(letter)

Modify execution: jump

The jump command lets you change which line will execute next. You can jump forward to skip code or backward to re-run lines, although pdb prevents many unsafe jumps (for example into frames where arguments aren’t defined). Use jump carefully when exploring how different flow affects state.

Common pdb commands (cheat sheet)

• list (l) — show source around current line
• step (s) — step into function calls
• next (n) — step over to the next line in the same frame
• continue (c) — resume execution until the next breakpoint or program end
• break (b) — set a breakpoint (file:line or function)
• tbreak — set a temporary breakpoint (clears after hit)
• clear — remove breakpoints
• disable / enable — turn a breakpoint off or on
• ignore — ignore a breakpoint a given number of hits
• pp — pretty-print an expression (pprint)
• args (a) — show the arguments of the current function
• return (r) — run until the current function returns
• jump (j) — set the next line to be executed
• quit / exit (q) — exit the debugger and abort the program

Tips and best practices

Use pdb in small, reproducible examples while learning. Embed pdb.set_trace() for quick local debugging, and combine conditional breakpoints with pp to inspect only the values you care about.

If you prefer a graphical or richer interactive experience, consider modern interactive debuggers and IDE integrations, but keep pdb in your toolkit—it's available everywhere Python runs and is invaluable when you need a lightweight, reliable command line python debugger.

Further reading

Refer to the official Python documentation for the pdb module and the pprint module to explore the full list of commands and advanced features. Practicing with the examples above will help you master common workflows such as how to use the python debugger and how to inspect variables in pdb.

Conclusion

The pdb module provides a powerful interactive debugger for debugging Python programs. Learning to set breakpoints, step through code, inspect variables, and alter execution flow will greatly speed up troubleshooting and improve your ability to find logic errors in Python code.