`uv python install --reinstall` cannot recover a dangling minor-version-link junction on Windows: "Missing expected target directory for Python minor version link"

[NextLevelManagementAdvisors]

Summary

On Windows, if the managed-Python minor version link junction (e.g. cpython-3.13-windows-x86_64-none) becomes dangling, every subsequent uv python install / uv python install --reinstall / uv run fails with:

error: Missing expected target directory for Python minor version link at C:\Users\<user>\AppData\Roaming\uv\python\cpython-3.13.13-windows-x86_64-none

uv does not self-heal this. --reinstall re-downloads and re-extracts the interpreter, but still fails at the link step, and re-creates a junction that also does not resolve. Even deleting the patch directory and .temp entirely and running a clean uv python install 3.13 reproduces the identical error. The only thing that fixes it is manually deleting the dangling junction and recreating it with a native Windows junction.

Environment

• uv 0.11.17 (a33a629 2026-05-28 x86_64-pc-windows-msvc)
• Windows 11
• uv installed via scoop; managed-Python dir at the default %APPDATA%\Roaming\uv\python
• Surfaced via a Claude Desktop MCP extension whose launch command is uv --directory <ext> run <pkg> (pinned to Python 3.13 via .python-version); every spawn hit the error and the MCP server disconnected.
• Note: not OneDrive-related (cf. uv python install fails with 'Failed to create Python minor version link directory (os error 448)' on Windows with OneDrive Files On-Demand #19616). The managed-Python directories have plain Directory attributes, no OneDrive placeholder / Offline / SparseFile reparse attributes.

On-disk state when broken

%APPDATA%\Roaming\uv\python\:

• cpython-3.13.13-windows-x86_64-none — real directory, complete and working. python.exe -V => Python 3.13.13 (exit 0); full stdlib present.
• cpython-3.13-windows-x86_64-none — a Junction whose Target correctly reads ...\cpython-3.13.13-windows-x86_64-none, but which enumerates 0 children (dangling at the OS level / does not resolve).

So the interpreter is fine; only the minor-version-link junction is broken, and that one broken junction poisons discovery and install.

Reproduction (verbose)

uv python install 3.13 --reinstall -v (stderr):

DEBUG Found download `cpython-3.13.13-windows-x86_64-none` for request `3.13 (cpython-3.13-windows-x86_64-none)`
DEBUG Downloading https://releases.astral.sh/github/python-build-standalone/releases/download/20260510/cpython-3.13.13%2B20260510-x86_64-pc-windows-msvc-install_only_stripped.tar.gz
DEBUG Extracting ... to temporary location: ...\uv\python\.temp\.tmpXXXXXX
Downloading cpython-3.13.13-windows-x86_64-none (download) (20.8MiB)
 Downloaded cpython-3.13.13-windows-x86_64-none (download)
DEBUG Removing existing directory: ...\uv\python\cpython-3.13.13-windows-x86_64-none
DEBUG Moving ...\uv\python\.temp\.tmpXXXXXX\python to ...\uv\python\cpython-3.13.13-windows-x86_64-none
DEBUG Inspecting existing executable at `C:\Users\<user>\.local\bin\python3.13.exe`
error: Missing expected target directory for Python minor version link at ...\uv\python\cpython-3.13.13-windows-x86_64-none

Observations:

1. The patch directory is re-created by the move and is valid, yet the install still fails at the minor-version-link step (exit code 2).
2. --reinstall does not remove/replace the pre-existing dangling cpython-3.13-... junction; the run ends with that junction still present and still enumerating 0 children.
3. Deleting the patch dir and .temp, then uv python install 3.13 from a clean state, fails identically.
4. When uv itself (re)creates the cpython-3.13-... junction during install, the result does not resolve (0 children). A junction created manually to the same target (New-Item -ItemType Junction / mklink /J) does resolve.

Workaround that actually fixes it

$base = "$env:APPDATA\uv\python"
$link = Join-Path $base 'cpython-3.13-windows-x86_64-none'
$patch = Join-Path $base 'cpython-3.13.13-windows-x86_64-none'
[System.IO.Directory]::Delete($link, $false)   # remove the dangling junction only (leaves the patch dir intact)
New-Item -ItemType Junction -Path $link -Target $patch | Out-Null

After this, uv python list --only-installed shows cpython-3.13.13 and uv run/uv python find use it normally.

Suggested fix

ensure_minor_version_link() should be idempotent / self-healing on Windows: if a minor-version-link junction already exists but does not resolve to a valid target (dangling reparse point), remove and recreate it rather than erroring with "Missing expected target directory". Discovery (find_all) could likewise treat a non-resolving managed-install junction as repairable/ignorable instead of hard-failing the whole operation.

Possibly related

• uv python install publishes managed Python before finalization, allowing uv python find to race and observe incomplete installs #19329 — uv python install publishes the managed Python before finalization (ensure_minor_version_link() runs late); an interrupted/raced install is a plausible way to end up with a published patch dir + a missing/broken minor-version link, i.e. the precondition for this bug.
• uv python install fails with 'Failed to create Python minor version link directory (os error 448)' on Windows with OneDrive Files On-Demand #19616 — same uv version, also a Windows minor-version-link-directory failure, but that one is OneDrive os error 448; this report is a different (non-OneDrive) manifestation at the validation site.

[shimabukuromeg]

Hi, I'm looking to make my first OSS contribution and ran into this issue in our environment.

When trying to use Python via uvx on Windows, I was hitting error: Missing expected target directory for Python minor version link at ... on every run. This occurred on uv 0.11.23, on two independent Windows machines.

Once it occurred, deleting the managed Python directory (%APPDATA%\uv\python) did not help — the error came back on reinstall, and it kept failing every time across several days and PC restarts.

We have Claude Desktop configured to launch multiple local MCP servers via uvx, and the logs showed two uvx processes going through the Python provisioning step simultaneously (both hitting this error within milliseconds of each other). I suspect a download/link-creation race like this left a broken link behind in the first place (possibly related to #19329).

As a fix, I would like to implement the first part of this issue's Suggested fix, in the link creation path (create_directory): after creating the link (or when a link already exists), verify that the target is actually reachable through the link; if it is not, remove the link and recreate it, and if that still does not resolve, fail with an explicit error. I am not planning to change the find_all side in this PR.

Would you accept a PR with this approach?

[zanieb]

Happy to look at a pull request.

[shimabukuromeg]

I looked into this, and it appears to be caused by MSIX filesystem virtualization, since Claude Desktop is packaged as an MSIX app. uv's managed Python physically lands in the package's LocalCache store, but the minor-version-link junction records its target as the logical (pre-virtualization) path (%APPDATA%\Roaming\uv\python\...) rather than the physical LocalCache location where the interpreter actually sits. That logical path doesn't exist as a real directory, so resolving through the junction gives Missing expected target directory. This seems to come from the MSIX environment rather than from uv itself.

Not planning to open a PR myself (looks MSIX-specific), but sharing in case it helps. Thanks!