Part 1: Getting Started with Debugging in VS Code

Introduction

I spent my first year as a developer debugging with print() statements. Need to see a variable's value? Add a print(). Code not behaving as expected? Add five more prints. Exception somewhere? Print everything until you find it.

Then I discovered VS Code's debugger. That single print-filled debugging session that took 45 minutes? With breakpoints, it took 3 minutes. This article shows you how to set up and start using the VS Code debugger for Python—the skill that fundamentally changed how I develop software.

Why Stop Using Print Statements?

The Print() Problem

def process_user_order(order_id, user_id):
    print(f"DEBUG: order_id={order_id}, user_id={user_id}")  # Added
    
    order = get_order(order_id)
    print(f"DEBUG: order={order}")  # Added
    
    user = get_user(user_id)
    print(f"DEBUG: user={user}")  # Added
    
    total = calculate_total(order)
    print(f"DEBUG: total={total}")  # Added
    
    # Bug is here somewhere...
    discount = apply_discount(user, total)
    print(f"DEBUG: discount={discount}")  # Added
    
    return total - discount

Problems:

• Clutter: Debug prints everywhere

• Slow: Add print, run, check output, repeat

• Limited: Can't inspect nested objects easily

• Cleanup: Must remove all prints before commit

• No control: Can't pause execution mid-function

The Debugger Solution

def process_user_order(order_id, user_id):
    order = get_order(order_id)  # ← Set breakpoint here
    user = get_user(user_id)     # Inspect order, user, everything
    total = calculate_total(order)
    discount = apply_discount(user, total)
    return total - discount

Set one breakpoint, see ALL variables, step through execution, evaluate expressions—all without modifying code.

Setting Up VS Code for Python Debugging

Install Python Extension

1. Open VS Code

2. Click Extensions (⇧⌘X)

3. Search "Python"

4. Install "Python" by Microsoft

5. Install "Debugger for Python" (usually auto-installed)

Verify Setup

Create a test file:

# test_debug.py
def greet(name):
    message = f"Hello, {name}!"
    return message

if __name__ == "__main__":
    result = greet("Developer")
    print(result)

Your First Debug Session

Method 1: Quick Start (No Configuration)

1. Open the file: Open test_debug.py

2. Set a breakpoint: Click in the gutter (left of line numbers) on line 3

   • Red dot appears

3. Start debugging: Press F5

4. Choose debugger: Select "Python Debugger"

5. Choose configuration: Select "Python File - Debug the currently active Python file"

VS Code pauses execution at your breakpoint!

Method 2: Using Run and Debug View

1. Open Run and Debug: Click the Run icon in sidebar or press ⇧⌘D

2. Create launch.json: Click "create a launch.json file"

3. Select Python: Choose Python debugger

4. Select configuration: Choose "Python File"

This creates .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

Now you can press F5 to debug the current file anytime.

Understanding the Debug Interface

When debugging starts, VS Code shows several panels:

1. Debug Toolbar (Top Center)

Continue (F5) | Step Over (F10) | Step Into (F11) | Step Out (⇧F11) | Restart (⇧⌘F5) | Stop (⇧F5)

2. Variables Panel (Left Sidebar)

Shows all variables in current scope:

VARIABLES
  ▼ Locals
    name: "Developer"
    message: "Hello, Developer!"
  ▼ Globals
    __name__: "__main__"
    greet: <function>

3. Watch Panel

Add expressions to monitor:

WATCH
  len(name)          → 9
  name.upper()       → "DEVELOPER"
  message.split()    → ["Hello,", "Developer!"]

4. Call Stack

Shows function execution path:

CALL STACK
  greet (test_debug.py:3)
  <module> (test_debug.py:7)

5. Breakpoints Panel

Lists all breakpoints:

BREAKPOINTS
  ✓ test_debug.py:3

6. Debug Console (Bottom)

Interactive Python REPL during debugging:

>>> name
'Developer'
>>> name + " is debugging"
'Developer is debugging'
>>> 2 + 2
4

Real Example: Debugging a FastAPI Endpoint

I built a REST API with a bug in user authentication. Here's how debugging found it.

The Buggy Code

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class LoginRequest(BaseModel):
    username: str
    password: str

users_db = {
    "alice": {"password": "secret123", "role": "admin"},
    "bob": {"password": "pass456", "role": "user"}
}

@app.post("/login")
def login(request: LoginRequest):
    user = users_db.get(request.username)
    
    if user is None:
        raise HTTPException(status_code=404, detail="User not found")
    
    # Bug somewhere here - authentication always fails!
    if user["password"] == request.password:
        return {"token": generate_token(user), "role": user["role"]}
    else:
        raise HTTPException(status_code=401, detail="Invalid password")

def generate_token(user):
    return f"token_{user['role']}_12345"

Problem: Login always returns 401 even with correct credentials.

Debugging Session

1. Set breakpoint on line 18: user = users_db.get(request.username)

2. Start debugger with FastAPI configuration:

{
    "name": "FastAPI",
    "type": "debugpy",
    "request": "launch",
    "module": "uvicorn",
    "args": ["main:app", "--reload"],
    "console": "integratedTerminal"
}

1. Send test request:

curl -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secret123"}'

1. Inspect in Debug Console:

>>> request.username
'alice'
>>> request.password
'secret123 '  # ← Extra space! That's the bug!
>>> user["password"]
'secret123'
>>> request.password == user["password"]
False

Found it! The client was sending "secret123 " with a trailing space. Fixed by stripping whitespace:

if user["password"] == request.password.strip():
    return {"token": generate_token(user), "role": user["role"]}

Without the debugger, I would have added print statements everywhere, restarted the server multiple times, and taken 30+ minutes. With breakpoints and the debug console, it took 2 minutes.

Common Debugging Scenarios

Scenario 1: Function Returns Wrong Value

def calculate_discount(price, user_level):
    discount_rates = {
        "bronze": 0.05,
        "silver": 0.10,
        "gold": 0.15
    }
    
    rate = discount_rates.get(user_level, 0)  # ← Breakpoint here
    discount = price * rate
    return discount

Set breakpoint, check:

• Is user_level what you expect?

• Is rate correct?

• Is price a number?

Scenario 2: Loop Not Working

def process_orders(orders):
    processed = []
    
    for order in orders:  # ← Breakpoint here
        if order["status"] == "pending":
            result = process_order(order)
            processed.append(result)
    
    return processed

Breakpoint in loop shows:

• What's in each order?

• Why is if condition failing?

• Is process_order() being called?

Scenario 3: Exception Somewhere

def update_user(user_id, data):
    user = get_user(user_id)  # ← Breakpoint before exception
    
    user.update(data)  # Exception: AttributeError
    save_user(user)
    
    return user

Inspect at breakpoint:

>>> user
None  # ← get_user() returned None!
>>> type(user)
<class 'NoneType'>

Debug Console REPL - Your Secret Weapon

The debug console isn't just for viewing variables—it's a Python REPL running in your code's context!

Testing Fixes Without Rerunning

def format_price(amount, currency="USD"):
    symbol = "$" if currency == "USD" else "€"
    return f"{symbol}{amount:.2f}"  # ← Breakpoint here

In debug console:

>>> amount
42.5
>>> currency
'EUR'  # Bug: symbol shows $ for EUR

# Test fix without editing code:
>>> symbol = "€" if currency == "EUR" else "$"
>>> f"{symbol}{amount:.2f}"
'€42.50'  # Works! Now update code

Exploring Object Structure

def process_api_response(response):
    data = response.json()  # ← Breakpoint here
    return data["results"]

In debug console:

>>> type(data)
<class 'dict'>
>>> data.keys()
dict_keys(['status', 'count', 'results', 'metadata'])
>>> data['results'][0]
{'id': 1, 'name': 'Item 1'}
>>> len(data['results'])
10

Debugging Best Practices

1. Start with Strategic Breakpoints

Don't scatter breakpoints everywhere. Place them at:

• Function entry points

• Right before suspicious code

• Inside conditionals that might be failing

• Before exceptions

2. Use the Call Stack

When execution pauses, the call stack shows how you got there:

process_order() → validate_order() → check_inventory() ← You are here

Click any frame to see its variables.

3. Debug Console Over Print

Instead of:

print(f"user: {user}, total: {total}, discount: {discount}")

Use debug console:

>>> user
{'id': 123, 'name': 'Alice', 'level': 'gold'}
>>> total
99.99
>>> discount
14.9985

4. Remove Breakpoints When Done

Too many breakpoints slow down debugging. Remove ones you don't need anymore.

Keyboard Shortcuts Summary

Action	Shortcut	Use When
Start/Continue	F5	Begin debugging or continue to next breakpoint
Toggle Breakpoint	F9	Add/remove breakpoint on current line
Step Over	F10	Execute current line, don't enter functions
Step Into	F11	Enter function calls
Step Out	⇧F11	Exit current function
Stop	⇧F5	End debugging session
Restart	⇧⌘F5	Restart from beginning

Common Issues and Fixes

"No module named 'uvicorn'" While Debugging

Create .vscode/launch.json with correct Python path:

{
    "configurations": [{
        "name": "FastAPI",
        "type": "debugpy",
        "request": "launch",
        "module": "uvicorn",
        "args": ["main:app", "--reload"],
        "console": "integratedTerminal",
        "python": "${workspaceFolder}/venv/bin/python"
    }]
}

Breakpoints Grayed Out

• File not saved - save it

• Python extension not installed

• Wrong Python interpreter selected (click bottom-right in VS Code)

Debug Console Not Working

Make sure you're in an active debug session (hit F5 and pause at breakpoint first).

What's Next

You now know how to:

• Set up VS Code for Python debugging

• Set breakpoints and start debug sessions

• Use the debug interface and console

• Debug real FastAPI applications

In Part 2: Breakpoints and Stepping Through Code, you'll learn different breakpoint types (conditional, logpoints, triggered), step controls, and efficient code navigation during debugging.

---

Based on debugging hundreds of Python applications in VS Code, from simple scripts to production FastAPI microservices.