Repository navigation
PEP-723 support for built-in venv #185
Description
Support for inline script metadata: https://peps.python.org/pep-0723/
What we need:
{{ message }}
PEP-723 support for built-in
venv #185Support for inline script metadata: https://peps.python.org/pep-0723/
What we need:
Activity
.pyfiles with inline metadata, add them as projects. #186.pyfiles and have inline metadata create custom transient environments. #187[-]PEP723 style environment support for built-in `venv`[/-][+]PEP-723 support for built-in `venv`[/+]StellaHuang95 commentedon May 19, 2026
Below are discussion items for this week's design review meeting.
TL;DR
Stages 1–2 of PEP 723 support (parse + detect) are implemented locally behind the
python-envs.useInlineScriptMetadatasetting.Stages 3–5 (env creation, rebuild on metadata change, telemetry / polish) are where most of the user-visible UX lives, and we want to align on six discussion items in the meeting before cutting more code.
Implementation status
# /// scriptblocks (requires-python,dependencies)What's implemented so far
When
python-envs.useInlineScriptMetadata = true:.pyfile. If it starts with a well-formed PEP 723# /// scriptblock, the file is auto-registered as a Python project, in its own row in the "Python Projects" tree view.Python Environments: Add Existing Projects→Inline Script Detectorto bulk-discover scripts in the open workspace folders (capped at 500, with the usual exclusions).When the setting is
false(the default while the feature is experimental) none of the above runs.Discussion items
Q1 — What does the "Create Environment" UI/flow look like for the two detection paths?
Context. We have two detection paths today (lazy on-open and the opt-in workspace scan). Both produce script projects with
env = undefined. The next chunk of work has to materialize an env for each one. The question is how the user is invited to do that.Path 1 — Lazy on-open/save detection
The user opens a single
.pyfile that turns out to have an inline# /// scriptblock. How is the env materialized?.venvnext tofoo.pyand install pandas, numpy?") and on accept creates the.venv. The status bar then flips to the normal interpreter indicator.# /// scriptblock, e.g. "▸ Create environment (pandas, numpy)". Clicking it triggers the same creation flow.Python: Create Environmentcommand.Path 2 — Opt-in workspace scan
After the user runs
Add Existing Projects → Inline Script Detectorand N script projects get registered in one pass, how do their envs get created?Q2 — Which tools do we support? Just
python -m venv, oruv/pipx/hatchtoo?Context. PEP 723 is tool-neutral by design. Several runners read the same
# /// scriptblock; each materializes and persists its own env differently. VS Code doesn't directly endorse any specific runner, but the env-creation stage has to pick one to materialize the env, or refuse and delegate. Conda is intentionally out of scope for v1 since PEP 723 dependencies are PyPI-shaped.How each tool supports PEP 723 today
Sourced from each tool's official docs.
uv run script.pyreads the# /// scriptblock, resolvesrequires-python+dependencies, materializes an environment on-demand, then runs the script.$XDG_CACHE_HOME/uvon Unix (e.g.~/.cache/uv);%LOCALAPPDATA%\uv\cacheon Windows. The per-script env is assembled by hardlinking from this cache.<script>.lockis present, subsequentuv run --scriptreuses the locked resolution.uv cache cleanoruv cache prune. No automatic TTL.pipx run script.pyreads the# /// scriptblock, creates a cached venv keyed to the script's dependency list withpython -m venv, installs the declared deps via pip, then runs the script.~/.local/share/pipx/), separate from thevenvs/directory used bypipx install.hatch run /path/to/script.pyreads the# /// scriptblock, creates a dedicated Hatch environment whose name is derived from the script's absolute path (e.g.SyB4bPbL), installs the declared deps with the chosen installer (uv by default; configurable to pip via[tool.hatch] installer = "pip"inside the metadata), then runs.<HATCH_DATA_DIR>/env/virtual/<derived-name>/. Default data dir:%USERPROFILE%\AppData\Local\hatchon Windows,~/Library/Application Support/hatchon macOS,$XDG_DATA_HOME/hatchon Linux. Override with--data-dirorHATCH_DATA_DIR.hatch env removeorhatch env prune. No automatic TTL.Alternatives we considered
.venvonlypython -m venv .venv(optionallyuv venvwhen the user already uses uv as their venv backend) next to the script, installs the metadata'sdependenciesvia pip, then points the status-bar interpreter selector, Pylance, and the debugger at.venv/bin/python. The user sees a real folder on disk and treats it like any other venv.numpy). Sibling.venvfolders accumulate. Doesn't match the dominant single-file workflow (uv run --script)..venvby default, uv-managed as an opt-in settingpython-envs.inlineScript.backend = "venv" | "uv") flips the backend to a uv-native mode where the extension shells out touv run --script/uv sync --scriptand lets uv build/locate its cached env (lives under%LOCALAPPDATA%\uv\cacheon Windows,~/.cache/uvon Unix — no folder next to the script). The choice can also be offered inside the Create Environment quick-pick. Status bar shows the resolved interpreter path inside uv's cache.requires-pythonhandled automatically); everyone else gets the simple sibling-.venvmodel. Doesn't lock users into one backend..venv(option A). Additionally, the extension scans known external tool caches (uv's cache, pipx's run-cache, Hatch's data dir) for envs that match the open script. Discovered envs show up in the Select Interpreter quick-pick alongside.venv, letting the user point Pylance/debugger at the env uv (or pipx, or Hatch) already built if their real workflow isuv run --scriptoutside VS Code..venv. Additive to A; doesn't conflict with B.Q3 — How do we persist the script's env? Forever, on a TTL, or cached by metadata hash?
Context. Sub-issue #187 uses the phrase "custom transient environments". "Transient" could mean short-lived (deleted on restart), content-addressed (one cache entry per unique metadata block), or just "separate from the workspace's main env, but otherwise normal". Whether "transient" was meant as "delete on restart" or "isolated from the workspace's main env" is one of the things this question needs to settle. A related sub-question for each option below is whether the env should appear in the Python Projects tree view alongside workspace envs, or stay hidden until the user clicks the script.
Alternatives we considered
.venv, persistent.venvfolder next to the script (e.g.foo.py→foo.py.venv/or shared.venv/per directory). Survives Code restarts and survives machine reboots; the user manages cleanup the same way they would any other venv. Env appears in the Python Projects tree view as a sibling of any workspace projects; status bar and Pylance point at it. Reads "transient" as relative to the workspace env, not short-lived..venvper script — disk usage scales with script count. No cross-script reuse. Visible clutter for users with many scripts in one directory. If users complain about clutter, the fix is either a cleanup command, a default TTL (→ option C), or a global cache (→ option D)..venv, GC'd on Code startup (or on extension activation).venvlayout as A, but on each Code startup (or extension activation) the extension removes every script-owned.venvit created. Re-running the script triggers a fresh creation. Reads "transient" literally..venv, TTL of N days unused.venvlayout as A, plus a background watch/timer that deletes envs whose script hasn't been opened/run for N days. "Unused" needs a precise definition (last access time? last Run/F5? last activation in a terminal?).pip listfrom the terminal count?).globalStorageUri/script-envs/<hash>/), keyed by a hash of the metadata block. Two scripts declaring the same deps share one env. Status bar shows the resolved interpreter path inside the cache; the env is not visible in the workspace folder. Mirrors howuv run --scriptreuses cached envs and is what the ecosystem norm looks like.pip installis a problem. uv deliberately hides these from end users; surfacing them in our tree view diverges from that UX..vscode/).vscode/script-envs/<hash>/per workspace folder. Persistent across restarts but not shared across machines or workspaces.Q4 — Is the env read-only, or can the user
pip installinto it?Context. PEP 723 declares dependencies inline. If the user installs a package via VS Code's "Install Package" command, we have two choices: (a) treat the env as a normal venv and allow it (the metadata becomes stale relative to the env), or (b) treat the env as read-only / declarative and refuse, redirecting the user to edit the metadata first.
This affects more than the explicit Install command — terminal
pip install, notebook/interactive installs, and any other channel face the same question. The spec's text is silent on whether the env should reflect only the metadata, but its "self-contained scripts" spirit points toward env ≡ metadata.Alternatives we considered
pip installwork as they do for any other project; the package lands in the env. The# /// scriptblock is never edited by the extension. Matches how the extension treatspyproject.toml-based projects today (installs don't auto-editpyproject.toml).ipython,pdbpp) without touching the script.uv run --script) won't see the extra deps; the script is no longer self-contained.# /// scriptblock to add/remove the dep. Requires a comment-preserving TOML writer.# /// script. Sync to metadata?" with action buttons.pip installis not intercepted, but any change made there is wiped on the next metadata-driven resync. The only supported way to add a dep is to edit the# /// scriptblock and let the extension rebuild. Strictly faithful to the spec.Q5 — Who is the audience: writers (full IDE experience) or runners (one-shot execute)?
Context. PEP 723 was designed in a tool-runner mindset: write a small script, drop a metadata block at the top, run with
uv run --script foo.py. The IDE is incidental. But VS Code users come in two distinct flavours when they hit a.pyfile with inline metadata:python foo.py, they're done. They don't need import resolution, refactor, breakpoints, or hover. Beginner-friendly; matches the spec's intent..pyfile: iterate, refactor, get Pylance completions, debug, write more code, add deps. The fact that the env-deps live in the file header is just a packaging convenience.A meaningful share of our audience is the author crowd, because VS Code is an IDE. But the spec's design centre is the runner crowd. This question forces us to be honest about which one our defaults serve. A third audience to keep in mind is publishers of single-file tools, who want to validate that their declared deps are minimal and correct before sharing.
Cross-extension caveat. The green Run button and the
pythondebug type (F5) are owned by the Microsoft Python extension (ms-python.python), not by us. We can create the script's env and surface it in our own UI (status bar, Projects view), but we can't unilaterally make Run/F5 launch with the script's env — that requires a coordinated change inms-python.python. This caveat bites option B the hardest: "Optimise for runners" is largely about making one-click execution feel native, so without that coordination we either ship v1 with Run/F5 still pointing at the workspace interpreter (and document the gap) or block v1 on the cross-extension work.Alternatives we considered
uv run --scriptsemantics: open, click, done.ms-python.python(see cross-extension caveat above).ranma42 commentedon Jul 14, 2026
related to: