Step-by-Step Guide to Debugging Python Code

Table of Contents

1. Understanding the Types of Bugs in Python
2. Step-by-Step Debugging Process
   • Step 1: Reproduce the Bug Consistently
   • Step 2: Read the Error Message (It’s Trying to Help!)
   • Step 3: Inspect Variables with Print Statements
   • Step 4: Use Python’s Built-in Debugger (pdb)
   • Step 5: Leverage IDE Debugging Tools (VS Code, PyCharm, etc.)
   • Step 6: Rubber Duck Debugging & Code Review
   • Step 7: Write Unit Tests to Prevent Regressions
3. Advanced Debugging Techniques
4. Common Pitfalls to Avoid
5. Conclusion
6. References

1. Understanding the Types of Bugs in Python

Before diving into debugging, it’s helpful to recognize the kinds of bugs you might encounter. Python bugs generally fall into three categories:

Syntax Errors

These occur when the code violates Python’s grammar rules. The interpreter will refuse to run the code until these are fixed.

Examples:

• Missing colons (:) after loops/conditionals.
• Incorrect indentation (Python uses whitespace to define blocks).
• Mismatched parentheses or quotes.

Example of a syntax error:

if x > 5  # Missing colon!
    print("x is large")

Error Message: SyntaxError: invalid syntax (points to the line with the missing colon).

Runtime Errors (Exceptions)

The code runs but crashes mid-execution due to invalid operations (e.g., dividing by zero, accessing a non-existent list index). Python raises an exception with a descriptive message.

Examples:

• ZeroDivisionError: Dividing by zero.
• IndexError: Accessing a list index that doesn’t exist.
• TypeError: Combining incompatible types (e.g., adding a string and an integer).

Example:

numbers = [1, 2, 3]
print(numbers[5])  # Index 5 doesn't exist!

Error Message: IndexError: list index out of range.

Logical Errors

The code runs without crashing but produces incorrect output. These are the trickiest bugs because the interpreter gives no warnings—you have to spot the flaw in logic.

Examples:

• Off-by-one errors (e.g., using < instead of <= in a loop).
• Incorrect arithmetic (e.g., total = price + tax instead of total = price * (1 + tax)).
• Misunderstanding function behavior (e.g., assuming a list is modified in-place when it’s actually copied).

Example:

def calculate_average(numbers):
    return sum(numbers) / len(numbers)  # Correct... but what if numbers is empty?

average = calculate_average([])  # No error, but causes ZeroDivisionError at runtime!

2. Step-by-Step Debugging Process

Let’s walk through a systematic workflow to diagnose and fix bugs, using a mix of tools and techniques.

Step 1: Reproduce the Bug Consistently

Before fixing a bug, you need to trigger it reliably. If the bug only happens “sometimes,” you can’t test whether your fix works.

How to Reproduce:

• Note the exact input/conditions that cause the bug (e.g., “It fails when the input list is empty”).
• Isolate variables: Test with a minimal, simplified version of your code (e.g., a small test case instead of a full dataset).
• Check your environment: Ensure dependencies, Python version, and configuration match the setup where the bug occurs (e.g., Python 3.9 vs. 3.11 may behave differently).

Step 2: Read the Error Message (It’s Trying to Help!)

Python’s error messages are surprisingly helpful—read them carefully. They include:

• Error type (e.g., IndexError, TypeError).
• Description (e.g., “list index out of range”).
• Traceback: A stack trace pointing to the exact line where the error occurred (and the sequence of function calls leading to it).

Example Traceback:

Traceback (most recent call last):
  File "app.py", line 5, in <module>
    print(numbers[5])
IndexError: list index out of range

Here, the error is in app.py, line 5: print(numbers[5]).

Step 3: Inspect Variables with Print Statements

The simplest debugging tool is also one of the most effective: print() statements. Use them to check the values of variables, function inputs/outputs, or loop iterations at critical points in your code.

Best Practices for Print Debugging:

• Print variable names and values for clarity: print(f"total: {total}") instead of print(total).
• Add context: print(f"Before loop: numbers = {numbers}") to track state changes.
• Use separators (e.g., print("---")) to group related outputs.

Example: Debugging a logical error in a sum function:

def sum_numbers(numbers):
    total = 0
    print(f"Initial total: {total}")  # Track start value
    for num in numbers:
        total += num
        print(f"Added {num}, new total: {total}")  # Track each step
    return total

sum_numbers([1, 2, 3])  # Should return 6

Output:

Initial total: 0
Added 1, new total: 1
Added 2, new total: 3
Added 3, new total: 6

If the output was wrong (e.g., 5 instead of 6), the print statements would reveal where the miscalculation occurred.

Step 4: Use Python’s Built-in Debugger (pdb)

For complex bugs, print() statements can get messy. Python’s built-in pdb (Python Debugger) lets you pause execution, inspect variables, and step through code line by line.

Basic pdb Commands

How to Use pdb

1. Insert a breakpoint in your code with import pdb; pdb.set_trace() (or break in pdb).
2. Run your script—the debugger will pause at the breakpoint.
3. Use the commands above to inspect and navigate the code.

Example: Debugging a function that returns an incorrect average:

def calculate_average(numbers):
    import pdb; pdb.set_trace()  # Breakpoint here
    total = sum(numbers)
    avg = total / len(numbers)
    return avg

calculate_average([2, 4, 6])  # Expected: 4, but let's say it returns 3...

Debugger Session:

> /path/to/script.py(3)calculate_average()
-> total = sum(numbers)
(Pdb) l  # List code
  1     def calculate_average(numbers):
  2         import pdb; pdb.set_trace()
  3  ->     total = sum(numbers)
  4         avg = total / len(numbers)
  5         return avg
(Pdb) p numbers  # Check input
[2, 4, 6]
(Pdb) n  # Execute next line (sum(numbers))
> /path/to/script.py(4)calculate_average()
-> avg = total / len(numbers)
(Pdb) p total  # Check sum result
12
(Pdb) p len(numbers)  # Check length
3
(Pdb) n  # Execute avg calculation
> /path/to/script.py(5)calculate_average()
-> return avg
(Pdb) p avg  # Oh! avg is 4.0 (correct). Maybe the bug is elsewhere?
4.0
(Pdb) c  # Continue execution

If avg was incorrect (e.g., 3), p total or p len(numbers) would reveal the miscalculation.

Step 5: Leverage IDE Debugging Tools

Most modern IDEs (VS Code, PyCharm, Spyder) include graphical debuggers that simplify stepping through code, setting breakpoints, and watching variables. These tools are more user-friendly than pdb for beginners.

Example: Debugging in VS Code

1. Open your Python file in VS Code.
2. Click the gutter (left margin) next to a line to set a breakpoint (red dot appears).
3. Run the script in debug mode (press F5 or click the “Run and Debug” icon in the sidebar).
4. Use the debug toolbar to:
   • Step over lines (F10).
   • Step into functions (F11).
   • Inspect variables in the “Watch” panel.
   • View the call stack (which functions led to the current line).

VS Code’s debugger visualizes variables and execution flow, making it easy to spot where things go wrong.

Step 6: Rubber Duck Debugging & Code Review

Sometimes, explaining your code to someone else (or even an inanimate object like a rubber duck) forces you to slow down and spot logical gaps. This is called “rubber duck debugging.”

How to Do It:

• Verbally walk through your code line by line, explaining what each part is supposed to do.
• When you hit a step that doesn’t make sense (e.g., “Then I add 1 to i, but the loop should stop when i equals n…”), you’ve likely found the bug.

For stubborn bugs, ask a peer to review your code. Fresh eyes often catch issues you’ve overlooked.

Step 7: Write Unit Tests to Prevent Regressions

Once you fix a bug, write a unit test to ensure it doesn’t reappear (a “regression”). Use frameworks like pytest or Python’s built-in unittest to automate testing.

Example with pytest:
Suppose you fixed calculate_average() to handle empty lists (by returning 0 instead of crashing). Write a test to verify this:

# test_average.py
import pytest
from my_script import calculate_average

def test_average_non_empty():
    assert calculate_average([2, 4, 6]) == 4.0

def test_average_empty_list():
    assert calculate_average([]) == 0.0  # New test for the fixed case

Run with pytest test_average.py. If the tests pass, you can be confident the bug is fixed—and stays fixed.

3. Advanced Debugging Techniques

For complex scenarios (e.g., multi-threaded code, remote servers), use these advanced tools:

Logging (Instead of Print Statements)

The logging module is more powerful than print() for debugging. It lets you:

• Log messages at different severity levels (DEBUG, INFO, WARNING, ERROR).
• Write logs to files (instead of the console) for later analysis.
• Disable debug logs in production with a single setting.

Example:

import logging

logging.basicConfig(
    filename="debug.log",  # Log to a file
    level=logging.DEBUG,  # Show DEBUG and higher messages
    format="%(asctime)s - %(levelname)s - %(message)s"
)

def process_data(data):
    logging.debug(f"Processing data: {data}")  # Detailed debug info
    result = data * 2
    logging.info(f"Processed result: {result}")  # General info
    return result

Remote Debugging

If your code runs on a remote server (e.g., a web app), use tools like debugpy (VS Code’s remote debugger) or pydevd (PyCharm) to connect to the remote process and debug locally.

Profiling for Performance Bugs

If your code runs slowly (a “performance bug”), use cProfile to identify bottlenecks:

python -m cProfile -s cumulative my_script.py  # Sort results by total time spent

This shows which functions consume the most resources.

4. Common Pitfalls to Avoid

• Ignoring error messages: Always read the full traceback—Python tells you exactly where and why it failed.
• Assuming “it can’t be that”: Bugs often stem from small mistakes (e.g., a typo in a variable name like totla instead of total).
• Not testing edge cases: Bugs love empty lists, negative numbers, or extreme values (e.g., 0, None, or 1e10).
• Mutable default arguments: A common gotcha! Default arguments are evaluated once when the function is defined, not on each call:

  def add_item(item, items=[]):  # items is reused across calls!
      items.append(item)
      return items
  
  print(add_item(1))  # [1]
  print(add_item(2))  # [1, 2] (unexpected!)

  Fix: Use None as the default and initialize inside the function:

  def add_item(item, items=None):
      if items is None:
          items = []
      items.append(item)
      return items

5. Conclusion

Debugging is a skill that improves with practice. By following this step-by-step process—reproducing the bug, reading error messages, using tools like pdb or IDE debuggers, and writing tests—you’ll turn frustrating bugs into opportunities to understand your code better.

Remember: Even expert developers debug daily. The key is to stay systematic, patient, and curious. Happy debugging!

6. References

• Python pdb Debugger Documentation
• VS Code Python Debugging Guide
• pytest Documentation
• Logging Module Documentation
• “Debugging with Python” (Real Python Tutorial)