Add uv fallback for inline script environments (PEP 723 PR 6/16) by StellaHuang95 · Pull Request #1696 · microsoft/vscode-python-environments

Stella Huang (StellaHuang95) · 2026-08-06T21:49:35Z

Part of #1602 (PEP 723 inline script env support). Design doc: #1601.

This replaces the earlier closed draft #1652 with the finalized implementation rebased on main.

Roadmap context

This is PR 6 of 16 in the PEP 723 inline-script roadmap. It extends the PR 5 create() happy path with the missing-compatible-interpreter fallback.

Phase 2: Manager	PR	Status
	PR 4: `InlineScriptEnvManager` skeleton	merged (#1610)
	PR 5a: generic env-creation utilities	merged (#1651)
	PR 5b: inline-script cache + interpreter utilities	merged (#1655)
	PR 5c: `create()` happy path	merged (#1656)
	PR 6: `create()` uv-install fallback	this PR
	PR 7: persistence (`get` / `set` + Memento)	separate follow-up

Why this PR

PR 5 can create or reuse an inline-script environment when an installed base interpreter already satisfies the script's requires-python. It deliberately stops when no compatible interpreter exists.

This PR adds the consent-gated fallback for that case:

Re-check installed interpreters after entering a narrow fallback queue.
Select a safe Python version satisfying the complete PEP 440 requirement.
Ask the user before installing uv or Python.
Refresh environment discovery after installation.
If discovery is stale or unavailable, resolve and validate uv's returned executable directly.
Continue through the existing PR 5 cache create/reuse path.

What this PR does

Adds the inline-script fallback to InlineScriptEnvManager.create()

Keeps the installed-interpreter path unchanged and only enters the fallback when no compatible base exists.
Skips installation prompts for quick-create/noninteractive calls.
Serializes only fallback installations, then re-checks discovery before prompting so concurrent compatible requests reuse one installation.
Retains successfully direct-resolved uv interpreters so queued requests can reuse them even while discovery remains stale.

Selects a safe uv target from requires-python

Uses simple safe selectors directly, such as >=3.13 → 3.13 and ==3.13.1 → 3.13.1.
Queries uv's advertised versions for bounded or exclusion-heavy constraints.
Restricts catalog candidates to default CPython 3 builds satisfying the complete specifier.
Handles exclusions such as >=3.13.2,!=3.13.2 without installing the excluded floor.
Uses an advertised release for bounded ranges rather than fabricating a potentially unavailable patch-zero release.
Applies full PEP 440 prerelease semantics consistently across discovery, catalog selection, direct resolution, and cache validation.
Normalizes accepted prerelease aliases (for example, c1 → rc1) before passing a version to uv.

Extends the uv installer's consent flow

Adds an inline-script-specific prompt that shows both the script requirement and selected Python version.
Sanitizes and caps script-controlled prompt details.
Validates install selectors before forwarding them to uv.
If catalog lookup is required and uv is missing, asks for consent to install uv first.
Re-checks whether a newly installed uv is usable by the current extension host and surfaces the existing restart-required message when needed.

Handles stale discovery after installation

Refreshes environment discovery after uv installs Python.
Treats refresh/discovery failures as recoverable.
Resolves the executable returned by uv directly, verifies that it satisfies requires-python, and canonicalizes its path before creating the cached environment.

Examples

`requires-python`	Fallback behavior
`>=3.13`	Request uv's `3.13` selector
`==3.13.1`	Request exactly `3.13.1` without requiring a catalog lookup
`>=3.11,<3.12`	Choose an advertised compatible `3.11.x` release
`>=3.13.2,!=3.13.2`	Skip `3.13.2` and choose a compatible advertised release
`>=3.15.0a1,<3.16`	Permit an explicitly requested prerelease
`>=3.14,<3.16`	Do not select a prerelease implicitly

Safety and concurrency

No uv or Python installation occurs without explicit user consent.
Script-derived values cannot inject arbitrary uv arguments.
Declined, cancelled, or failed installations do not mutate the script-environment cache.
The fallback queue does not globally serialize environment selection or normal cache creation.
Existing cross-process cache locking and rollback behavior from PR 5 remains unchanged.

Tests

Coverage includes:

simple, exact, bounded, exclusion, and prerelease requirements;
uv catalog filtering and consented uv bootstrap;
declined and failed installations;
refresh and discovery failures with direct resolution;
simultaneous same- and different-constraint requests;
quick-create prompt suppression;
strict post-install and cache compatibility checks;
prompt sanitization and install-selector validation.

npm run compile-tests, npm run lint, the full unit suite, and the focused inline-script/uv suites are clean.

User impact

No default-path user impact yet. This completes an internal Phase 2 manager capability. Automatic routing and user-facing entry points arrive in later roadmap PRs.

When those entry points are wired, users whose scripts require an unavailable Python will be able to approve installing a compatible interpreter rather than having environment creation stop.

Stella Huang (StellaHuang95) · 2026-08-06T22:26:32Z

🔒 Automated review in progress — Stella Huang (@StellaHuang95) is auto-reviewing this PR.

Eduardo Villalpando Mello (edvilme) · 2026-08-06T22:33:14Z

        let candidates = derivedChecks
            .filter((candidate) => !candidate.derived)
-            .map((candidate) => candidate.environment);
+            .map((candidate) => candidate.environment)
+            .filter(
+                (candidate) =>
+                    !metadata.requiresPython ||
+                    this.matchesInstallConstraint(metadata.requiresPython, candidate.version),
+            );


Maybe thes can be combined into something like

let candidates = derivedChecks .filter((candidate) => !candidate.derived && (!metadata.requiresPython || this.matchesInstallConstraint(metadata.requiresPython, candidate.version) ) .map((candidate) => candidate.environment)

It can be combined but it's mainly for readability concerns, and I don't see any meaningful performance difference. I personally don't prefer compact forms but I don't mind changing it.

Eduardo Villalpando Mello (edvilme) · 2026-08-06T22:33:42Z


        while (candidates.length > 0) {
-            const environment = pickCompatibleInterpreter(candidates, metadata.requiresPython);
+            const environment = pickCompatibleInterpreter(candidates, undefined);


Suggested change

const environment = pickCompatibleInterpreter(candidates, undefined);

const environment = pickCompatibleInterpreter(candidates);

This is intentional just to call the helper to validate the already compatible candidates.

Eduardo Villalpando Mello (edvilme) · 2026-08-06T22:34:24Z

+        this.baseInterpreterInstallationQueue = run.then(
+            () => undefined,
+            () => undefined,
+        );


I am not entirely sure what does this mean

will add a comment

Eduardo Villalpando Mello (edvilme) · 2026-08-06T22:35:43Z

+
+        const installedPath = await this.installPythonAndRefresh(requiresPython, version);
+        if (!installedPath) {
+            return undefined;


Maybe we can try catching this?

installPythonAndRefreshalready already catches prompt/install errors and refresh failures, while undefined is the expected result for a declined, cancelled, or handled failed installation.

Eduardo Villalpando Mello (edvilme) · 2026-08-06T22:38:03Z

+        return selected;
+    }
+
+    private async selectInstallablePythonVersion(


Maybe this is a followup PR, but I think we could create a PythonVersion class that can handle extracting lower/upper bounds, testing regexes, comparing, ensuring versions match constraints, etc.

Add consent-gated uv installation when no installed interpreter satisfies a script. Coalesce matching installs, skip prompts for quick create, and directly resolve a successful installation when discovery is stale or unavailable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1a9f6ba1-9bd3-4664-bc25-a0d34d7a2e91

Eduardo Villalpando Mello (edvilme)

:)

Stella Huang (StellaHuang95) requested review from Eduardo Villalpando Mello (edvilme) and Eleanor Boyd (eleanorjboyd) August 6, 2026 21:54

Stella Huang (StellaHuang95) mentioned this pull request Aug 6, 2026

Add inline script environment persistence (PEP 723 PR 7/16) #1697

Open

Stella Huang (StellaHuang95) added the feature-request Request for new features or functionality label Aug 6, 2026

Eduardo Villalpando Mello (edvilme) reviewed Aug 6, 2026

View reviewed changes

Stella Huang (StellaHuang95) force-pushed the pep723-pr6-uv-fallback branch from 2c8302b to d58cf31 Compare August 7, 2026 17:14

address feedback

21fb1d2

Eduardo Villalpando Mello (edvilme) approved these changes Aug 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add uv fallback for inline script environments (PEP 723 PR 6/16) - #1696

Add uv fallback for inline script environments (PEP 723 PR 6/16)#1696
Stella Huang (StellaHuang95) wants to merge 2 commits into
microsoft:mainfrom
StellaHuang95:pep723-pr6-uv-fallback

Stella Huang (StellaHuang95) commented Aug 6, 2026 •

edited

Loading

Uh oh!

Stella Huang (StellaHuang95) commented Aug 6, 2026

Uh oh!

Uh oh!

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 7, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 7, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 7, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 7, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 6, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	const environment = pickCompatibleInterpreter(candidates, undefined);
	const environment = pickCompatibleInterpreter(candidates);

Uh oh!

Conversation

Stella Huang (StellaHuang95) commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Roadmap context

Why this PR

What this PR does

Examples

Safety and concurrency

Tests

User impact

Uh oh!

Stella Huang (StellaHuang95) commented Aug 6, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Eduardo Villalpando Mello (edvilme) left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Stella Huang (StellaHuang95) commented Aug 6, 2026 •

edited

Loading