Skip to content
Tutorials Center
My learning

Topics

Lesson 71 of 149 ยท Files and Errors

Debugging and assert

Learn to debug Python code. Read tracebacks from the bottom up, use print debugging well, check assumptions with assert, log with the logging module, and meet pdb.

Every programmer writes bugs. The difference between a beginner and an experienced developer isn't the number of bugs they write; it's how quickly they find and fix them. Debugging is a skill you can learn, and it starts with a calm, systematic approach rather than random changes and hope.

In this lesson you'll learn to read a traceback properly, use print() debugging effectively, state your assumptions with assert, replace scattered prints with the logging module, and get a first look at pdb, Python's interactive debugger.

A debugging mindset

When something goes wrong, work through these steps:

  1. Reproduce the problem. Find the smallest input that triggers it every time.
  2. Read the error message and traceback. Really read it; it usually says exactly what happened.
  3. Form a guess about the cause, then check it by looking at actual values.
  4. Fix one thing at a time, then run the code again.
  5. Keep the failing case as a test, so the bug can't silently come back (see Testing).

The biggest trap is step 3: assuming you know what a variable contains instead of looking. Most bugs live in the gap between what you think the program does and what it actually does.

Reading a traceback

Run this program. It crashes inside a helper function that's called from another function:

Python A traceback with several frames

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the traceback from the bottom up:

  • The last line is the exception type and message: ZeroDivisionError: division by zero. That's what happened.
  • The frame just above it is the line that raised it: return sum(values) / len(values) inside average. That's where.
  • The frames further up show how you got there: the print(summarize(scores)) line at the bottom called summarize, which called average in its loop.

So the question becomes: why was len(values) zero? Looking at the data, Ben has no scores. The traceback points at average, but the real decision to make is what an empty list should mean: maybe the function should return None, or skip that student. The line that crashes is not always the line that's wrong.

Tip: in Python 3.11 and later, tracebacks often underline the exact part of a line that failed with ^^^^ markers. That's very helpful in long expressions like data["users"][0]["name"], where any of the lookups could be the culprit.

The simplest debugging tool is print(). There's nothing wrong with it, as long as you print useful things. Two habits make a big difference:

  • Print labels with values, so you know which print produced which line.
  • Use repr() (or !r in f-strings) so strings show their quotes and hidden characters. The f-string = specifier does both at once: f"{price=}" prints price=9.99.
Python Finding a bug with prints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The word "cat" appears three times, but the function returns 2. The debug output shows why: token='' from the double space, and token='cat\nslept,' where a line break joined two words. Splitting on a single space was the bug. text.split() with no argument splits on any run of whitespace and fixes it. Try that change, then remove the debug print.

The downside of prints is cleanup: you have to remember to delete them, and they can't be switched on and off. That's where logging comes in.

Checking assumptions with assert

An assert statement states something you believe must be true at a certain point. If it's true, nothing happens. If it's false, Python raises AssertionError with your optional message:

Python assert

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Asserts are perfect for catching your own mistakes early, close to the cause, instead of letting a wrong value travel through the program. They also document assumptions for the next reader of the code.

Watch out: don't use assert to validate user input or data from outside your program. Running Python with the -O (optimize) flag removes every assert statement, so the check would silently disappear. For input validation, raise a real exception such as ValueError, as shown in Raising Exceptions. And never write assert(condition, "message") with parentheses: that asserts a non-empty tuple, which is always true.

The logging module

logging is the grown-up version of print debugging. Each message has a level that says how important it is, and you choose with one setting which levels actually appear. You can leave the log calls in your code permanently and turn the detail up or down when you need it.

The five standard levels, from least to most severe, are DEBUG, INFO, WARNING, ERROR and CRITICAL.

Python Logging basics

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Change level=logging.DEBUG to logging.WARNING and run again: only the warning remains. That one switch is the main advantage over print().

A few conventions:

  • Call logging.basicConfig() once, at the start of the program, not in library code.
  • Create a named logger per module with logging.getLogger(__name__), so the output shows where each message came from.
  • Pass values as arguments (log.info("total %s", total)) rather than building an f-string. The text is only formatted if the message is actually shown.
  • Inside an except block, log.exception("message") logs at ERROR level and includes the full traceback.

By default, log messages go to standard error rather than standard output. In real applications you can also send them to files, with timestamps, using handlers.

The interactive debugger: pdb

Sometimes you'd like to pause a program in the middle and look around. Python's built-in debugger, pdb, does exactly that. Put this line where you want to stop:

Python
breakpoint()

When the program reaches it, you get a (Pdb) prompt in your terminal where you can type commands:

Command What it does
p expression Print the value of an expression, such as p total
n (next) Run the current line and stop at the next one
s (step) Step into a function call on the current line
c (continue) Run until the next breakpoint
l (list) Show the source code around the current line
w (where) Show the call stack, like a traceback
q (quit) Stop the program

You can also run a whole script under the debugger with python -m pdb script.py, and after a crash, python -m pdb -c continue script.py drops you into the debugger at the point of the error. Editors such as VS Code and PyCharm offer the same features graphically: click in the margin to set a breakpoint, then step through the code and watch variables change.

Note: pdb needs an interactive terminal, so it doesn't work in the editors on this page. Use prints, asserts and logging here, and try breakpoint() when you run Python on your own computer (see Running Python Code).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where should you start reading a Python traceback?

    The last line says what went wrong, and the frame just above it says where. Then read upward to see how the program got there.
  2. 2. What does print(f"{total=}") print when total is 42?

    The = specifier prints the expression's text, an equals sign and its value, which is ideal for quick debug prints.
  3. 3. Why shouldn't you validate user input with assert?

    Optimized mode strips asserts, so the check would vanish. Raise ValueError or another real exception for input validation.
  4. 4. With logging.basicConfig(level=logging.WARNING), which call produces output?

    Only messages at the configured level or above appear. ERROR is more severe than WARNING, so it's shown; DEBUG and INFO are not.
  5. 5. Which line pauses a program and opens the pdb prompt?

    The built-in breakpoint() starts pdb at that point (when running in an interactive terminal).

Summary

  • Debug systematically: reproduce, read the error, check real values, fix one thing, keep a test.
  • Read tracebacks bottom up: the exception and message, then the failing line, then the calls that led there.
  • Print debugging works best with labels and repr(); f"{name=}" does both.
  • assert condition, "message" catches your own mistakes early, but never use it for input validation.
  • logging gives messages levels (DEBUG to CRITICAL) that you can filter with one setting; log.exception() includes the traceback.
  • breakpoint() opens pdb for stepping through code in a terminal or editor.

Next: Logging and Warnings.