Use `fastapi run` for FastAPI debug configs, with file and project variants by savannahostrowski · Pull Request #1048 · microsoft/vscode-python-debugger

savannahostrowski · 2026-06-01T17:14:03Z

A draft for #1045 - opening this to make the proposed approach a bit more concrete. Happy to adjust based on the open discussion before marking it review ready (there are some open questions to align on in the issue).

This updates the FastAPI debug configuration (both the launch.json snippet and the dynamic provider) to use the fastapi CLI instead of invoking uvicorn directly:

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.

This replaces the previous uvicorn main:app --reload config and its hand-rolled main.py detection.

I have run the tests and manually tested as well.

rchiodo · 2026-06-01T17:24:04Z

/azp run

savannahostrowski · 2026-06-01T17:24:07Z

@microsoft-github-policy-service agree [company="FastAPI Labs"]

azure-pipelines · 2026-06-01T17:24:11Z

Azure Pipelines could not run because the pipeline triggers exclude this branch/path.

savannahostrowski · 2026-06-01T17:24:46Z

@microsoft-github-policy-service agree company="FastAPI Labs"

savannahostrowski · 2026-06-01T18:52:54Z

So just closing the loop here and reconciling threads from #1045, since the PR only changes what the snippet flow writes when a user newly invokes "Add Configuration" and what the dynamic provider suggests in-memory for users without a launch.json, anyone with module: uvicorn already in their launch.json keeps that exact config and continues to work.

I've also added tiered auto-detection so monorepo/nested layouts don't break out of the box:

Auto-detection (applied in both flows):

1 match at workspace root → plain fastapi run
1 match in a subdirectory → fastapi run (auto-passed)
2+ matches → snippet prompts the user (pre-filled with the first detection); dynamic provider falls back to plain fastapi run

The snippet flow also prompts on 0 matches (with no pre-fill). The dynamic provider doesn't surface FastAPI configs at all if 0 are detected.

rchiodo · 2026-06-01T19:05:53Z

+export async function buildFastAPIWithFileLaunchDebugConfiguration(
+    _input: MultiStepInput<DebugConfigurationState>,
+    state: DebugConfigurationState,
+): Promise<void> {


Copilot generated:
The Architect notes the ['run', '${file}'] config literal now lives in two places (here and dynamicdebugConfigurationService.ts), and the ['run'] default is encoded both in tryResolveFastApiArgs and as ?? ['run'] in the dynamic caller. Hoist to a shared constant / small helper to prevent drift. Low priority.

[verified]

I tried this but extracting ['run', '${file}'] into a readonly string[] constant required spreading at every call site ([...FASTAPI_RUN_FILE_ARGS]), which was longer than the inline literal.

rchiodo · 2026-06-01T20:01:48Z

    return fastApiPaths;
 }

+export function tryResolveFastApiArgs(folder: WorkspaceFolder, paths: readonly Uri[]): string[] | undefined {


Copilot generated:
Unresolved from prior review (Medium): path.relative emits OS-native separators, so a single subdir match persists "args": ["run", "backend\\app\\main.py"] on Windows. A launch.json shared to macOS/Linux then runs fastapi run backend\app\main.py, which treats backslashes literally and fails despite correct detection. The Skeptic notes the central fix actually broadened exposure here (root single-matches previously emitted separator-free ['run']). Normalize to POSIX in the persisted arg (e.g. relative.split(path.sep).join('/')) and confirm fastapi run accepts forward slashes on Windows.

[verified]

@savannahostrowski what did you think of this idea? Does fastapi work with forward slashes on Windows?

rchiodo · 2026-06-01T20:01:57Z

-        const appPyPath = path.join(folder.uri.fsPath, 'main.py');
-        pathExistsStub.withArgs(appPyPath).resolves(false);
-        const file = await fastApiLaunch.getApplicationPath(folder);
+        const state = { config: {}, folder };


Copilot generated:
The Skeptic notes the nested-match expectations use path.join('backend','app','main.py'), which produces the resolver's own OS-specific output on every platform — the separator assertion is tautological and will never catch the portability bug above. Once the persisted arg is normalized to POSIX, assert the literal 'backend/app/main.py' instead.

[verified]

Of course that other change would affect this test if you modified it to use forward slashes.

savannahostrowski · 2026-06-23T20:12:30Z

@rchiodo I addressed most of the comments you've left. The two outstanding are tied to the path-separator decision I called out in this thread.

Happy to revisit if you'd prefer to normalize across all three providers, but didn't want to diverge from the existing pattern unilaterally.

Let me know if there's anything else you'd like changed!

rchiodo · 2026-06-23T20:19:09Z

@savannahostrowski can you merge/rebase on main? The tests fail because of an unrelated issue which I just submitted a fix for on the main branch.

rchiodo · 2026-07-06T21:50:15Z

🔒 Automated review in progress — @rchiodo is auto-reviewing this PR.

rchiodo · 2026-07-06T22:01:17Z

-        module: 'uvicorn',
-        args: ['main:app', '--reload'],
+        module: 'fastapi',
+        args,


module: 'fastapi' runs python -m fastapi run …, which requires fastapi-cli (fastapi[standard]) or FastAPI ≥ 0.111. The previous module: 'uvicorn' worked with a bare uvicorn install, so environments that debugged fine before can now fail immediately with No module named fastapi.__main__. Consider detecting CLI availability or surfacing an actionable message, and document the minimum FastAPI/fastapi-cli requirement.

rchiodo · 2026-07-06T22:01:20Z

+    if (paths.length !== 1) {
+        return undefined;
+    }
+    const relative = path.relative(folder.uri.fsPath, paths[0].fsPath);


path.relative yields OS-native separators (e.g. backend\app\main.py on Windows) that get baked into args and persisted to launch.json. A committed launch.json should be portable; consider normalizing to POSIX separators (fastapi run accepts / on Windows) so a shared config works cross-platform.

rchiodo · 2026-07-06T22:01:23Z

+    }
+    const relative = path.relative(folder.uri.fsPath, paths[0].fsPath);
+    return ['run', relative];
+}


Multi-root workspace edge case: getFastApiPaths uses workspace-wide workspace.findFiles, so tryResolveFastApiArgs(folder, paths) can compute path.relative(folder, fileInAnotherFolder) → ..\otherFolder\main.py, which is then passed straight to fastapi run and points outside the folder. Consider filtering detected paths to the target folder, or treating cross-folder matches as "not a single match" and falling back to plain run.

rchiodo · 2026-07-06T22:01:25Z

+                request: 'launch',
+                module: 'fastapi',
+                args: ['run', '${file}'],
                jinja: true,


The "FastAPI File" (${file}) variant is only pushed inside if (fastApiPaths?.length), so a user whose app doesn't match the app\s*=\s*FastAPI\( regex (e.g. application = FastAPI(), a factory pattern, or app in __init__.py) gets neither config — even though fastapi run ${file} would work on their open file. The ${file} variant doesn't depend on project detection; consider offering it independently of the detection gate.

rchiodo · 2026-07-06T22:01:28Z

+    }
+    const relative = path.relative(folder.uri.fsPath, paths[0].fsPath);
+    return ['run', relative];
+}


tryResolveFastApiArgs returns undefined for BOTH "0 matches" and ">1 matches", and the two callers resolve that ambiguity differently (dynamic provider → ?? ['run']; interactive builder → prompt). This is intentional and tested, but undocumented. Add a one-line comment stating it returns args only for an unambiguous single match and that callers decide how to handle 0-or-many, so a future maintainer doesn't "fix" it and break one path.

rchiodo · 2026-07-06T22:01:31Z

+        const state = { config: {}, folder };
+        getFastApiPathsStub.resolves([Uri.parse(path.join('one', 'two', 'backend', 'app', 'main.py'))]);
+
+        await fastApiLaunch.buildFastAPILaunchDebugConfiguration(instance(input), state);


The prefill computed at fastapiLaunch.ts (path.relative(workspaceRoot, fastApiPaths[0].fsPath)) is never asserted — the multi-match test stubs showInputBox but doesn't check the value (prefill) argument, so a wrong prefill would pass CI. Also untested: the telemetry fields autoDetectedFastAPIMainPyPath/manuallyEnteredAValue and the state.folder === undefined branch. Consider adding assertions for the prefill value and telemetry payload.

rchiodo · 2026-07-06T22:01:34Z

Approach looks reasonable. The main things worth aligning on before marking review-ready: the switch from uvicorn to the fastapi CLI raises a runtime dependency (fastapi-cli / FastAPI ≥ 0.111), the detected path is baked into launch.json with OS-native separators, and the workspace-wide path detection can produce cross-folder relative paths in multi-root workspaces. None are blocking, but they affect portability and edge-case correctness.

rchiodo

Approved via Review Center.

rchiodo added the debt Code quality issues label Jun 1, 2026