Adding print() calls shows only the values you thought to print. A debugger lets you pause a running program, look at any variable and move through the code one line at a time. By the end of this guide, you will be able to start Python’s built-in debugger, pdb, use its core commands and inspect a program after it crashes.

The commands come from the pdb documentation. The sessions below were run with Python 3.14 and are real (long folder paths are shortened to ...).

The bug to find

This function should return the average of three marks, 80.0, but it prints 30.0:

def average(marks):
    total = 0
    for m in marks:
        total = m
    return total / len(marks)

print(average([70, 80, 90]))

1. Pause the program with breakpoint()

The built-in breakpoint() function, described on the built-in functions page, drops you into the debugger at the line where you call it. Add it inside the loop, just after line 4, save the file as average_bp.py and run it:

    for m in marks:
        total = m
        breakpoint()
$ python3 average_bp.py
> .../average_bp.py(5)average()
-> breakpoint()
(Pdb) p m, total
(70, 70)
(Pdb) c
> .../average_bp.py(5)average()
-> breakpoint()
(Pdb) p m, total
(80, 80)

The first line names the file, the line number (5) and the function. The arrow shows the line about to run, and (Pdb) is the prompt. p prints the value of an expression, and c continues until the program stops again. On the second pass, total should be 150 (70 plus 80), but it is 80. Line 4 replaces the total instead of adding to it. Changing it to total += m makes the script print 80.0.

2. Start pdb from the command line

You can also debug a script without editing it. Running python3 -m pdb pauses before the first line:

$ python3 -m pdb average.py
> .../average.py(1)<module>()
-> def average(marks):
(Pdb) b 4
Breakpoint 1 at .../average.py:4
(Pdb) c
> .../average.py(4)average()
-> total = m
(Pdb) a
marks = [70, 80, 90]
(Pdb) ll
  1  	def average(marks):
  2  	    total = 0
  3  	    for m in marks:
  4 B->	        total = m
  5  	    return total / len(marks)
(Pdb) n
> .../average.py(3)average()
-> for m in marks:
(Pdb) p total
70

b 4 sets a breakpoint on line 4, a prints the function’s arguments and ll lists the whole function. In that listing, B marks the breakpoint and -> marks the current line.

3. The commands you will use most

Most commands have a short form. The documentation writes them as n(ext), meaning you can type n or next. Pressing Enter on an empty line repeats the last command.

  • p expression: print a value. pp pretty-prints it.
  • n(ext): run the current line and stop at the next line in the same function.
  • s(tep): run the current line, stopping inside any function it calls.
  • c(ont(inue)): run until the next breakpoint.
  • b(reak): set a breakpoint by line number or function name. A condition can follow, as in b 4, m == 90.
  • r(eturn): run until the current function returns.
  • w(here): print the stack trace, with the newest frame at the bottom.
  • q(uit): leave the debugger and stop the program.

4. Inspect a crash after it happens

When run with -m pdb, the debugger enters post-mortem mode if the program ends with an error. Here, empty.py holds the fixed function but calls average([]), which divides by zero:

$ python3 -m pdb empty.py
> .../empty.py(1)<module>()
-> def average(marks):
(Pdb) c
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
Uncaught exception. Entering post mortem debugging
Running 'cont' or 'step' will restart the program
> .../empty.py(5)average()
-> return total / len(marks)
(Pdb) p marks, total
([], 0)

You land on the line that failed, with that function’s variables still there to inspect. They show that the list was empty.

Common mistakes

  • Leaving breakpoint() in finished code. The program will stop and wait for input. Remove it, or set the environment variable PYTHONBREAKPOINT=0, which the sys module documentation says turns breakpoint() into a call that does nothing.
  • Variable names that match commands. pdb runs anything it recognizes as a command, so typing n moves to the next line even if your code has a variable called n. Use p n or put ! in front of a Python statement.
  • Using n when you meant s. next runs called functions at nearly full speed without stopping inside them. Use step to follow a call.
  • Quitting when you meant to continue. q aborts the program. Since Python 3.14, quitting from a breakpoint() session asks for confirmation first. Use c to let the program finish.

Start with breakpoint(), p, n and c, which are enough to watch a value change line by line. Add python3 -m pdb and post-mortem mode when a crash needs a closer look, and type help at the prompt whenever you forget a command.