FastAPI Debug Launch with debugpy

This reference provides practical .vscode/launch.json patterns for FastAPI applications started with uvicorn.

Launch FastAPI via Module

Preferred profile:

{
  "name": "FastAPI: Uvicorn (debug)",
  "type": "debugpy",
  "request": "launch",
  "module": "uvicorn",
  "args": [
    "your_package.main:app",
    "--host",
    "127.0.0.1",
    "--port",
    "8000",
    "--reload",
    "--log-level",
    "debug"
  ],
  "cwd": "${workspaceFolder}",
  "envFile": "${workspaceFolder}/.env",
  "console": "integratedTerminal",
  "justMyCode": true,
  "jinja": true
}

Why module mode: it matches python -m uvicorn ... behavior and avoids path ambiguity.

Launch with Factory Pattern

If app is created via factory function:

{
  "name": "FastAPI: Uvicorn factory (debug)",
  "type": "debugpy",
  "request": "launch",
  "module": "uvicorn",
  "args": [
    "your_package.main:create_app",
    "--factory",
    "--host",
    "127.0.0.1",
    "--port",
    "8000",
    "--reload"
  ],
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal",
  "justMyCode": true
}

Attach to an Existing FastAPI Process

If the app is launched externally, start with debugpy:

python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload

Attach profile:

{
  "name": "FastAPI: Attach (5678)",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "127.0.0.1",
    "port": 5678
  },
  "justMyCode": true
}

Common FastAPI Debug Pitfalls

Wrong import target in your_package.main:app or factory symbol.
cwd does not match source layout.
Auto-reload creating confusion about active process when breakpoints are set in startup code.
Port collisions from old uvicorn processes.
Environment variables not loaded because envFile path is wrong.

Practical Quality Gate

A profile is considered valid when:

Server starts from VS Code Run and Debug.
A breakpoint inside an endpoint is hit on request.
A breakpoint in startup/lifespan logic is hit at app boot.
Terminal output appears in integrated terminal with expected log level.

2.2 KiB Raw Blame History