How to debug a FastAPI application line by line in VS Code

To debug a FastAPI application line by line in VS Code, you’ll want to set up a proper launch configuration using the built-in debugger. Here’s how to do it step by step:

---

✅ 1. Ensure Your Environment is Set

• VS Code installed ✅

• Python extension installed ✅

• FastAPI and Uvicorn installed ✅

---

✅ 2. Create a launch.json for Debugging

This file tells VS Code how to run and debug your FastAPI app.

1. In VS Code, go to the Run and Debug sidebar (Ctrl+Shift+D).

2. Click “create a launch.json file” if you haven’t already.

3. Choose Python as the environment.

4. Replace the generated config with this:

.json

{ "version": "0.2.0", 
"configurations": 
[ 
{ "name": "FastAPI Debug", "type": "python", "request": "launch", "module": "uvicorn", 
"args": [ "main:app", // replace with your app's entry point "--reload" ], 
"jinja": true, "env": { "PYTHONPATH": "${workspaceFolder}" }, 
"console": "integratedTerminal" } 
] 
}

🔁 Replace main:app with the actual path to your FastAPI app, for example app.main:app if it's in app/main.py.

---

✅ 3. Set Breakpoints

• Open any .py file in your FastAPI app.

• Click on the left margin to set breakpoints (red dot).

---

✅ 4. Start Debugging

• Press F5 or click the green play button.

• The server will start with debugging enabled.

• When a request hits a breakpoint, VS Code will pause there.

• You can now step through line by line using:

  • F10 → step over

  • F11 → step into

  • Shift+F11 → step out

---

Optional Tips

🔍 Debug Specific Endpoint:

Add a test route and hit it in your browser or with a tool like Postman or curl. When it hits the breakpoint, you’ll be able to inspect variables and control flow.

🛑 Common Pitfall:

If breakpoints are not hit, check:

• You’re using uvicorn in module mode (module:app) not file path.

• --reload is enabled for hot-reloading.

• You're not running the app manually in a terminal (use the debugger instead).