Split FastAPI debug config into file-scoped and project-scoped options

[savannahostrowski]

Hey folks 👋 I work at @fastapilabs and maintain https://github.com/fastapi/fastapi-vscode. I've been looking at the broader FastAPI experience in VS Code and wanted to open an issue to discuss an improvement we've been discussing related to debugging.

The current FastAPI debug configurations (the snippet from microsoft/vscode-python#14606 and the dynamic provider added in #19505) launch the app via uvicorn ...:app --reload and rely on hand-rolled main.py detection. This predates the fastapi CLI (fastapi run / fastapi dev), which provides built-in app discovery via pyproject.toml or default file locations.

For an improved experience, I'd like to propose splitting the current debugging experience into two options:

• Debug FastAPI with current file - runs fastapi run ${file} against the currently active file. This is optimal for single-file apps or quickly debugging a specific entry point.

• Debug FastAPI - runs plain fastapi run and lets the CLI discover the app via pyproject.toml or default file locations. Doing this would also remove the extension's own detection logic in favor of the FastAPI CLI's resolution, and give users a clearer choice between file-scoped and project-scoped debugging.

Wanted to gauge whether there'd be appetite for this change. I already have a branch with most of this working locally and would be happy to put up a PR if it makes sense.

Thanks!

[rchiodo]

Hi Savannah :)

The change sounds good especially if you're volunteering to do it :)

What would the launch.json look like?

This is the current version:

    {
      "name": "Python Debugger: FastAPI",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": ["main:app", "--reload"],
      "jinja": true
    },

Would we get this?

    {
      "name": "Python Debugger: FastAPI Current File",
      "type": "debugpy",
      "request": "launch",
      "module": "fastapi",
      "args": ["run", "${file}"],
      "jinja": true
    },
    {
      "name": "Python Debugger: FastAPI ",
      "type": "debugpy",
      "request": "launch",
      "module": "fastapi",
      "args": ["run"],
      "jinja": true
    },

What about version detection? I'm assuming this only works with certain versions of FastAPI or is the 'run' command recognized in older versions of FastAPI?

I'm also wondering about subprocess creation. Does the 'fastapi run' command run the app itself or does it launch a subprocess? That might complicate debugging, especially if the user doesn't want subprocess debugging turned on for other subprocesses

[savannahostrowski]

Hi Rich, thanks for the quick reply! 🙂

To answer your questions:

• launch.json shape: yes, your proposed configs are essentially what I have locally!

• run vs dev (or --reload): I chatted with Sebastián a bit about this and we're leaning toward using fastapi run without --reload. --reload spawns a uvicorn subprocess to watch for file changes, which interacts awkwardly with the debugger. The debugger already has a restart button that covers the "I changed code, restart" workflow. It's a bit different than today's workflow but it seems to sidestep some debugger UX issues.

• Version detection / fallback: Originally, I was going to propose detecting the CLI via the interpreter and having a fallback path that still used uvicorn for users without the CLI installed. However, because fastapi-cli has been around since FastAPI 0.111 (May 2024), I would lean towards just pointing users at this path that depends on FastAPI CLI. If it's missing, the CLI surfaces a clear "install fastapi-cli" error at runtime, which is better than us silently substituting uvicorn (which isn't really a true equivalent anyway). If we do want to keep an uvicorn option around, maybe it deserves a separate entry labeled as such rather than mixing them under "FastAPI."

One other thought - today's dynamic provider converts the detected file path into a module string (e.g. uvicorn backend.app.main:app --reload), which sometimes lets monorepo layouts work without extra config. Switching to plain fastapi run shifts app resolution to the CLI, which auto-discovers relative to cwd. For nested layouts, the canonical fix is to declare [tool.fastapi] entrypoint in pyproject.toml (the FastAPI docs explicitly recommend this approach for tools like VS Code: https://fastapi.tiangolo.com/fastapi-cli/#configure-the-app-entrypoint-in-pyproject-toml). Users without an entrypoint can add "cwd": "${workspaceFolder}/<their dir>" to the launch config as a workaround. There might be things we can do here to encourage setting the entrypoint?