Debugging FastAPI Applications in VS Code: A Complete Guide

Running your FastAPI server from the terminal? Your breakpoints won’t work. Here’s how to properly set up debugging in VS Code so you can step through your code with confidence.

The Problem

You’ve set a breakpoint in VS Code, started your FastAPI server with uvicorn app.main:app, and tested your endpoint through the Swagger docs. But nothing happens—the breakpoint is never hit.

This is one of the most common frustrations when developing FastAPI applications. The issue is simple: when you run uvicorn from the terminal, VS Code’s debugger isn’t attached to that process. Your breakpoints exist only in the editor, but the running server has no knowledge of them.

The Solution: Debug Configuration

Instead of running your server from the terminal, you need to launch it through VS Code’s debugger. This ensures the debugger is properly attached and your breakpoints will work as expected.

Step 1: Create launch.json

1. Open the Run and Debug panel by clicking the play icon with a bug in the left sidebar (or press Ctrl+Shift+D)
2. Click “create a launch.json file” if you don’t have one already
3. Select “Python Debugger” from the dropdown
4. Choose “FastAPI” or “Python File” as the configuration type

Step 2: Configure for FastAPI

Replace the contents of .vscode/launch.json with this configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "FastAPI Debug",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "app.main:app",
                "--reload",
                "--host", "0.0.0.0",
                "--port", "8000"
            ],
            "jinja": true,
            "justMyCode": true,
            "console": "integratedTerminal"
        }
    ]
}

Important: Replace "app.main:app" with your actual module path. If your FastAPI app is in main.py at the root, use "main:app". If it’s in a different structure, adjust accordingly.

Step 3: Start Debugging

1. Stop any running servers in your terminal (press Ctrl+C)
2. Set your breakpoint by clicking in the gutter next to the line number (a red dot will appear)
3. Press F5 or click the green play button in the Run and Debug panel
4. Wait for the server to start—you’ll see “Uvicorn running on…” in the integrated terminal

Now when you test your endpoint through the Swagger docs at http://localhost:8000/docs, your breakpoint will be hit.

Debugging Controls: Laptop-Friendly Shortcuts

On many laptops, function keys trigger system actions instead of VS Code commands. Here’s how to navigate your code while debugging:

Using the Debug Toolbar

If keyboard shortcuts aren’t working, use the floating debug toolbar that appears at the top of VS Code when debugging. The icons from left to right are:

• Continue (play icon) – Resume execution until next breakpoint
• Step Over (curved arrow over dot) – Execute the current line without entering functions
• Step Into (arrow pointing down) – Go inside the function being called
• Step Out (arrow pointing up) – Exit the current function
• Restart (circular arrow) – Restart the debugging session
• Stop (square) – Stop debugging

Understanding Step Into vs Step Over

When your breakpoint hits a line like return create_user(db, user), you have two options:

Step Into (F11): Takes you inside the create_user function so you can debug its implementation line by line. Use this when you need to understand what’s happening inside the function.

Step Over (F10): Executes the entire create_user function and moves to the next line. Use this when you trust the function works correctly and just want to continue debugging the calling code.

Common Troubleshooting

Breakpoint not being hit?

• Verify you started the server using F5 in VS Code, not from the terminal
• Check that your breakpoint is on an executable line (not on comments or blank lines)
• Ensure you’re making the correct HTTP request type (GET, POST, etc.)
• Confirm you’re hitting the right endpoint path in Swagger docs

Can’t find launch.json?

The file should be at .vscode/launch.json in your project root. If the .vscode folder doesn’t exist, create it manually and add the launch.json file inside it.

Server still running on port 8000?

If you get an “Address already in use” error, another process is using port 8000. Find and stop it:

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Linux/Mac
lsof -i :8000
kill -9 <PID>

Debugging FastAPI applications becomes straightforward once you understand that VS Code needs to launch your server, not just attach to a running process. With proper configuration, you gain full access to breakpoints, variable inspection, step-through debugging, and all the powerful tools that make development faster and less error-prone.

Set up your launch.json once, and you’ll never have to worry about breakpoints not working again. Happy debugging!

Top Rated Book On Amazon Check