Debugging with print, breakpoint() and pdb

A traceback tells you where a program stopped. Many bugs give you no traceback at all: the program runs to the end and prints a wrong answer. Debugging is the work of finding which line does something other than what you meant, and it goes fastest when you stop guessing and look at what the program actually does, one value at a time.

This lesson uses one small bug throughout. It finds the bug with print(), then with the debugger pdb in a terminal, and then shows where the same controls are in the debugger of an editor.

Start with a bug you can repeat

This function should return the average of a list of marks. For 70, 80 and 90 the answer is obviously 80:

def average(marks):
    total = 0
    i = 1
    while i < len(marks):
        total += marks[i]
        i += 1
    return total / len(marks)


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

56.666666666666664

It prints 56.666… instead, and no error tells you why. Before you change anything:

1. Make the bug small and repeatable. Three marks whose right answer you can work out by hand beat a real class list: you know what every intermediate value should be.
2. Explain the code line by line. Say, out loud or in writing, what each line does with these marks. Explaining to someone, or to a rubber duck on your desk, makes you read what is written instead of what you meant to write, and many bugs turn up at this step.
3. Form a guess and check it, as below. Change one thing at a time, and run the program again after each change.

Print the values that matter

The quickest check is a print() where you suspect the problem. Print the values the next line depends on, with a label, so the output says what each number is:

def average(marks):
    total = 0
    i = 1
    while i < len(marks):
        print(f"before adding: {i=} {marks[i]=} {total=}")
        total += marks[i]
        i += 1
    print(f"after the loop: {total=} {len(marks)=}")
    return total / len(marks)


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

before adding: i=1 marks[i]=80 total=0
before adding: i=2 marks[i]=90 total=80
after the loop: total=170 len(marks)=3
56.666666666666664

The output shows the loop adding 80 and 90 and never 70: i starts at 1, so the first mark, at position 0, is skipped. The fix is i = 0. Delete the prints once the bug is fixed, or they will clutter every later run.

The = inside the braces of an f-string does the labelling for you: f"{total=}" prints the expression, an equals sign and the value. The spaces you write around = appear in the output too, and any expression works, not only a name:

price = 249.5
quantity = 3
name = "Notebook "

print(f"{price=}")
print(f"{quantity = }")
print(f"{price * quantity = }")
print(f"{price * quantity = :.2f}")
print(f"{name=}")

price=249.5
quantity = 3
price * quantity = 748.5
price * quantity = 748.50
name='Notebook '

Without a format such as :.2f, the value is shown the way repr() shows it, so strings get quotes and the space at the end of "Notebook " becomes visible. Invisible characters at the ends of text are a common reason why two strings that look equal are not.

Pause the program with breakpoint()

Prints show what you thought to ask for. A debugger lets you stop the program and ask anything. Python’s own debugger, pdb, is in the standard library: put breakpoint() on a line of its own where you want the program to stop, and run the program in a terminal as usual. When Python reaches the call, pdb shows where the program has stopped and waits at its prompt, (Pdb), for commands:

• n (next): run the current line, including any function it calls, and stop at the next line here.
• s (step): run the current line, but stop inside a function it calls.
• c (continue): run on until the next breakpoint or the end of the program.
• r (return): run on until the current function returns.
• p and an expression: print its value, as in p total or p marks[i].
• ll (longlist): list the source code of the current function.
• w (where): show the chain of calls that led to the current line.
• q (quit): stop the program.

Here is the average function again, with breakpoint() just before the line that calls it:

def average(marks):
    total = 0
    i = 1
    while i < len(marks):
        total += marks[i]
        i += 1
    return total / len(marks)


marks = [70, 80, 90]
breakpoint()
print(average(marks))

pdb needs a person at a terminal to type the commands, which a web page cannot offer. So the session below was recorded by a short program, session.py, which runs python3 average_debug.py exactly as you would and types the commands for you. Its output is what you would see on screen, with two differences: pdb prints the whole path of the file where this page shows only its name, and a terminal adds colours:

import re
import subprocess
import sys

# What you would type, in order: commands at each (Pdb) prompt, then y to confirm q.
typed = ["n", "s", "n", "n", "n", "p i, marks[i]", "p marks[0]", "w", "q", "y"]

# Run the program the way `python3 average_debug.py` does, with the typing done for you.
result = subprocess.run(
    [sys.executable, "average_debug.py"],
    input="\n".join(typed) + "\n",
    capture_output=True,
    text=True,
)

# Without a terminal, nothing shows what was typed, so put each line back after its prompt.
answers = iter(typed)
print("$ python3 average_debug.py")
for part in re.split(r"(\(Pdb\) |\[y/n\] )", result.stdout):
    if part in ("(Pdb) ", "[y/n] "):
        print(part + next(answers))
    elif part.strip():
        print(part, end="")

$ python3 average_debug.py
> average_debug.py(11)<module>()
-> breakpoint()
(Pdb) n
> average_debug.py(12)<module>()
-> print(average(marks))
(Pdb) s
--Call--
> average_debug.py(1)average()
-> def average(marks):
(Pdb) n
> average_debug.py(2)average()
-> total = 0
(Pdb) n
> average_debug.py(3)average()
-> i = 1
(Pdb) n
> average_debug.py(4)average()
-> while i < len(marks):
(Pdb) p i, marks[i]
(1, 80)
(Pdb) p marks[0]
70
(Pdb) w
  average_debug.py(12)<module>()
-> print(average(marks))
> average_debug.py(4)average()
-> while i < len(marks):
(Pdb) q
Quitting pdb will kill the process. Quit anyway? [y/n] y

Each stop shows the file, the line number in brackets and the function (<module> for code outside any function), then, after ->, the current line: the one that runs next. The session uses n to reach the call, s to step into average() (pdb prints --Call-- as it enters the function), and n three more times to reach the loop. There p i, marks[i] shows that the loop starts at position 1, with 80, while p marks[0] shows the 70 that will never be added. w lists the two frames: the line of the file that called average(), and the current line inside it, marked with >.

A line that is not a pdb command runs as Python in the program, so total on its own shows the value of total, and total = 0 would change it. When a variable has the same name as a command, such as n, write p n or put ! in front of the line.

Turn breakpoints off

breakpoint() calls sys.breakpointhook(), which first reads the environment variable PYTHONBREAKPOINT. Set it to 0 and every breakpoint() call does nothing, so you can run the program normally without editing it:

import os
import subprocess
import sys

# The same program with the environment variable PYTHONBREAKPOINT set to 0.
env = {**os.environ, "PYTHONBREAKPOINT": "0"}
result = subprocess.run([sys.executable, "average_debug.py"], env=env, capture_output=True, text=True)

print("$ PYTHONBREAKPOINT=0 python3 average_debug.py")
print(result.stdout, end="")

$ PYTHONBREAKPOINT=0 python3 average_debug.py
56.666666666666664

Remove breakpoint() calls once you have fixed the bug. When a program runs where nobody can type, as a scheduled job or behind a Run button on a web page, pdb reads the end of the input, takes it as q, and the program ends on that line. To debug a program without editing it at all, start it with python3 -m pdb average.py: pdb stops before the first line, and you set breakpoints with b and a line number, then c to run to them.

The debugger in your editor

Editors put the same controls behind buttons and a panel of variables, which many people find easier than typing commands. In Visual Studio Code with its Python extension, which installs the Python Debugger extension with it:

• Click in the margin to the left of a line number, or press F9, to set a breakpoint on that line; it shows as a red circle.
• Press F5, or select Run and Debug in the Run and Debug view, then choose Python Debugger and Python File. The program runs until it reaches a breakpoint.
• Step with F10 (step over, pdb’s n), F11 (step into, s) and Shift+F11 (step out, pdb’s r: run until the current function returns); F5 continues.
• The Variables section shows the local and global variables of the frame you select, Watch shows expressions you choose each time the program stops, and Call Stack is pdb’s w.
• A conditional breakpoint stops only when an expression is true, such as i == 2, and a logpoint writes a message to the Debug Console without stopping, like a print() that is never in your code, so there is nothing to delete afterwards.

Other editors offer the same ideas under similar names. IDLE, the editor in Python’s standard library (an optional part, which some Python installations leave out), has a simpler debugger: choose Debug, then Debugger, in the Shell window, then run your file from the editor; IDLE’s documentation calls it incomplete and somewhat experimental. No lesson of this track needs a particular editor, and pdb works wherever Python runs in a terminal.

Debugging in the browser

The Run buttons of these lessons and the Python Online Compiler give a program its input before it starts and show what it prints, so there is no terminal for pdb to wait at. In the browser, debug with print() and f"{name=}"; save pdb and your editor’s debugger for Python on your own computer.

Key takeaways

• Debug a small input whose right answer you know, explain the code line by line, and change one thing at a time.
• Print the values the suspect line depends on, with labels; f"{expression=}" writes the label for you and shows strings with quotes, so stray spaces show up.
• breakpoint() stops the program in pdb: n runs a line, s steps into a call, p prints a value, c continues, w shows where you are and q quits.
• PYTHONBREAKPOINT=0 turns every breakpoint() off; remove them when the bug is fixed.
• An editor’s debugger offers the same with breakpoints in the margin, step buttons and a panel of variables.