With `cache-python: true`, a Windows runner can report a cache hit while
extracting the cache incorrectly. When `@actions/cache`'s tar extracts
uv's minor-version junction before the patch directory it points to, it
creates a file symlink. Resolving that link later raises `[WinError 5]
Access is denied`.
This PR fixes things up after restoring the Python cache, recreating the
junction if resolving the link fails with access denied and its recorded
target is a matching, accessible CPython installation in the same
directory.
This is a temporary workaround until
https://github.com/actions/toolkit/issues/2562 gets resolved and
`@actions/cache` itself becomes resilient to these situations.
I tested this by restoring the same archive on two fresh `windows-2022`
runners. The original run passed because resolving the minor-version
link raised the expected WinError 5. With the patch, `uv sync --offline
--managed-python --no-python-downloads` created a virtual environment
whose `home` in `pyvenv.cfg` resolved to the cached CPython 3.10.22
installation. [Original
run](https://github.com/astral-sh/ruff/actions/runs/41469344610/job/125358623949#step:9:1)
· [Patched
run](https://github.com/astral-sh/ruff/actions/runs/41469344610/job/125358623835#step:10:1).
## Summary
When the uv version is read from dependencies (`requirements.txt`, or
`project.dependencies` / `optional-dependencies` / `dependency-groups`
in `pyproject.toml` via `version-file`), the specifier was matched with
`/^uv([=<>~!]+\S*)/`. PEP 508 allows whitespace around operators and
after commas, and those valid forms were misread:
| dependency | before | after |
|---|---|---|
| `uv >= 0.5.0` | not found, latest uv installed | `>=0.5.0` |
| `uv == 0.11.20` | not found, latest uv installed | `==0.11.20` |
| `uv>=0.5.0, <0.6.0` | `>=0.5.0,`, fails with `No version found for
>=0.5.0,` | `>=0.5.0,<0.6.0` |
The regex now allows whitespace around operators and between
comma-separated clauses, and strips it from the result. Inputs that
worked before give the same result, including inline `--hash=` options,
trailing ` # comments`, the `\` continuation lines from `uv pip compile
--generate-hashes`, and names that only start with `uv` (`uvicorn`,
`uv-build`).
## Test plan
- Added cases for spaced operators, spaced clauses, inline `--hash` and
trailing comments. The four whitespace cases failed before the change.
- `npm run all` on Ubuntu (WSL) with Node 24.19.0: build, Biome (no
fixes), packaging, and 165 tests across 15 suites pass. The rebuilt
`dist/setup/index.cjs` only differs in the changed line.
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## Summary
`~=` is the PEP 440 compatible release operator, but the resolver tries
`semver.validRange()` first, and semver accepts `~=` as a tilde range:
| specifier | semver | PEP 440 |
|---|---|---|
| `~=0.9` | `>=0.9.0 <0.10.0` | `>=0.9, ==0.*` |
So with the default `highest` strategy, `version: "~=0.9"` (or
`required-version = "~=0.9"` picked up through `version-file`) installs
the highest 0.9.x instead of the highest 0.x. The same happens with
`manifest-file`, where `tc.evaluateVersions` is semver-based.
This skips the semver evaluation for specifiers containing `~=`, so they
are only evaluated with `@renovatebot/pep440`. No semver range
legitimately uses `~=`.
Notes:
- Only a bare two-segment `~=X.Y` resolved incorrectly. `~=X.Y.Z` gives
the same result in both, and compound specifiers like `~=0.9, !=0.9.3`
were already rejected by semver and fell through to PEP 440.
- `minSatisfying` gets the same check for consistency. The lower bound
is the same under both interpretations, so `lowest` didn't produce wrong
results before.
- A single-segment `~=1` is invalid PEP 440. semver used to resolve it
to 1.x; it now fails with `No version found for ~=1`, same as other
invalid specifiers.
## Test plan
- Added tests for `~=0.9` with the default manifest and with
`manifest-file`. Both returned `0.9.26` instead of `0.10.2` before the
change.
- `npm run all` on Ubuntu (WSL) with Node 24.19.0: build, Biome (no
fixes), packaging, and 161 tests across 15 suites pass. The rebuilt
`dist/setup/index.cjs` only differs in the changed lines.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## Summary
The post step logs `uv cache saved with key: ...` (and `Python cache
saved with key: ...`) even when the save failed. The log in #769 shows
it right after `Warning: Failed to save: ...`:
```
Warning: Failed to save: "C:\Program failed with error: The process 'C:\Program Files\Git\usr\bin\tar.exe' failed with exit code 2
uv cache saved with key: setup-uv-2-x86_64-pc-windows-msvc-windows-11-3.12.12-pruned-...
```
`@actions/cache`'s `saveCache` doesn't throw for these failures. It logs
them and returns `-1`, and `saveCacheToKey` ignored the return value.
This now checks for `-1` before logging, which is the same check the
`actions/cache` save step uses (`if (cacheId != -1) core.info("Cache
saved with key: ...")`). `@actions/cache` already logs the reason, so
nothing else is logged on failure, and the exit code stays the same.
This only changes the log line. It doesn't address the underlying
tar/gzip failure in #769. One limitation: with the legacy (v1) cache
service, an upload that fails after the cache was reserved still returns
the reserved id, so that one case is still reported as saved. That's on
the `@actions/cache` side and affects `actions/cache` the same way.
Related to #769
## Test plan
- Added `__tests__/cache/save-cache.test.ts`. The `-1` case fails before
the change and passes after it.
- `npm run all` on Ubuntu (WSL) with Node 24.19.0 / npm 11.17.0: build,
Biome (no fixes), packaging, and all 161 tests across 16 suites pass.
The regenerated `dist/save-cache/index.cjs` only differs in the changed
lines.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## Summary
- Preserve class names in the save-cache bundle so `@actions/cache`
error-name comparisons distinguish validation errors, benign
cache-reservation races, and finalization errors correctly.
- Add regression coverage that exercises the bundled `ValidationError`,
`ReserveCacheError`, and `FinalizeCacheError` constructors.
Fixes#1028
## Verification
- `npm run all` passed on Ubuntu 24.04 with Node 24.19.0: build, Biome,
packaging, and all 159 tests across 15 suites.
- `git diff --check` passed.
The save-cache bundle increases by about 77 KB raw (14 KB gzip) to
preserve the required names.
Windows ARM64 jobs may need x64 Python independently of their Python
version pin. Add `python-arch` to export `UV_PYTHON_ARCH` for subsequent
steps and include the selected architecture in the uv and managed-Python
cache keys. The input takes precedence over an inherited environment
value, and unsupported uv versions fail before environment creation.
Requires a uv release with `UV_PYTHON_ARCH` support.
https://github.com/pyca/cryptography/pull/15572#discussion_r3913508686
has the context for this: TL;DR our current `python-version` output
mirrors the "request" version exactly, which means that it's
insufficient for any downstream that needs to manage its own cache keys
(since caches shouldn't be shared across release candidates, but the `uv
python` request version doesn't include RC numbers).
The first commit here was my attempt to fix this by exposing the runtime
Python version, but this too is imprecise: the runtime version doesn't
indicate the interpreter variant (e.g. freethreading), which is also
important to capture in the cache identity.
My solution here is to expose `python-runtime-id`, which is just the
`key` of the active Python version from `uv python list
--output-format=json`.
---------
Signed-off-by: William Woodruff <william@yossarian.net>
`setup-uv` currently ignores the `sha256` supplied by the default
`astral-sh/versions` manifest when a selected artifact is newer than its
bundled checksum table, allowing that download to proceed without
validation. Use the manifest checksum as a fallback after explicit and
bundled checksums, and reject manifest entries that do not provide one.
This preserves the stronger pinned hashes for known releases while
verifying newer releases without requiring an action update. Part of
#1032.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
Co-authored-by: William Woodruff <william@yossarian.net>
Co-authored-by: Kevin Stillhammer <kevin.stillhammer@gmail.com>
Transient timeout fetching manifests have increased significantly
recently, especially with private runners.
```
Fetching manifest data from https://raw.githubusercontent.com/astral-sh/versions/main/v1/uv.ndjson ...
Error: The operation was aborted due to timeout
```
Retry transient manifest network failures up to three times with a
progressive backoff (not exponential), keeping the total wait bounded
while making setup resilient to short network blips.
Co-authored-by: Raymond <arguile-@users.noreply.github.com>
## Summary
- reject path-like uv versions from `.tool-versions`
- reject path-like Python versions from `.tool-versions`
- document the restriction and cover Unix and Windows paths in tests
## Testing
- `npm ci --ignore-scripts`
- `npm run all`
Refs: pi-session 019ff4bb-8b7c-7c4b-8bdf-7c188dfa2e3f
## Summary
Roll up the remaining net changes from the open Dependabot updates:
- release-drafter/release-drafter 7.7.0 (#990)
- github/codeql-action 4.37.4 (#987, #988, #989)
- zizmorcore/zizmor-action 0.6.1 (#986)
- @actions/cache 6.2.0 (#975)
- @biomejs/biome 2.5.4 (#974)
- undici 8.7.0 (#973)
The Jest 30.4.2 (#905) and @renovatebot/pep440 5.0.0 (#907) updates are
already present on main and require no additional changes.
This also updates the Biome schema, applies the formatter changes from
Biome 2.5.4, and regenerates the published bundles.
## Testing
- `npm run all`
- `actionlint`
- `git diff --check`
Refs: pi-session 019ff01b-f917-73c1-950e-2966956f263c
## Summary
- add `latest-known` as an explicit version selector
- resolve it locally to the newest version in the bundled checksum table
- preserve existing default and `latest` behavior
- document custom-manifest checksum semantics and update published
bundles
## Testing
- `npm ci --ignore-scripts`
- `npm run all` (99 tests passed)
Closes#919
Refs: pi-session 019fed0e-6019-7504-911b-bd9955cbbd49
## Summary
- disable `enable-cache: auto` for `pull_request_target`,
`workflow_run`, and `release` events
- disable automatic caching for tag pushes while leaving branch pushes
unchanged
- preserve explicit `enable-cache: true` as an override
- run a `workflow_run` integration fixture with `act` in pull request CI
and verify caching is disabled
- document the behavior and update the published bundles
## Testing
- `npm run all`
- `actionlint .github/workflows/test.yml
__tests__/workflows/workflow-run.yml`
- `uvx zizmor __tests__/workflows/workflow-run.yml`
Closes#984
Refs: pi-session 019fec42-9b26-714e-a359-830ac4401ecd
## Summary
This changes the default for `prune-cache` from `true` to `false`,
motivated by [#745](https://github.com/astral-sh/setup-uv/issues/745).
Users that want the existing behavior can continue to set `prune-cache:
true` explicitly.
Some history: I originally added [`uv cache prune
--ci`](https://github.com/astral-sh/uv/pull/5391) after looking at a
workload where the uv cache was ~2.2 GB, almost entirely due to the
enormous pre-built `torch` and `nvidia_cudnn_cu12` wheels ([original
analysis](https://github.com/actions/setup-python/issues/822#issuecomment-2248728264)).
Persisting and restoring thousands of extracted files through the GitHub
Actions cache could be slower than downloading the wheels again. In
contrast, wheels built from source can be very expensive to recreate.
The intent was to remove pre-built wheels while retaining locally-built
wheels.
`setup-uv` subsequently made pruning configurable, but defaulted
`prune-cache` to `true`; it also later enabled caching by default on
GitHub-hosted runners. As a result, the default configuration repeatedly
downloads pre-built wheels from PyPI even on a cache hit. That tradeoff
has become more important as uv adoption has grown: [the PyPI analysis
in
#745](https://github.com/astral-sh/setup-uv/issues/745#issuecomment-3867334064)
estimates that uv accounts for roughly half of reported CI downloads
from PyPI, and roughly 65-75% for `boto3`.
I ran the comparison across a few different workloads:
| Workload | PR | Packages | Cache: keep / prune / prune-ci | Warm
restore+sync: keep / prune / prune-ci | Downloads: prune / prune-ci |
|---|---:|---:|---:|---:|---:|
| Tiny | [#1](https://github.com/astral-sh/setup-uv-benchmarks/pull/1) |
19 | 6 / 6 / 2 MB | 0.3-0.4 / 0.3 / 0.4-0.5 s | 0 / 2 |
| Web | [#2](https://github.com/astral-sh/setup-uv-benchmarks/pull/2) |
65 | 43 / 43 / 7 MB | 0.6-1.0 / 0.5-0.6 / 1.5-1.7 s | 0 / 6 |
| Scientific |
[#3](https://github.com/astral-sh/setup-uv-benchmarks/pull/3) | 118 |
586 / 586 / 8 MB | 8.2-16.0 / 7.0-8.2 / 8.9-12.1 s | 0 / 19 |
| PySpark |
[#4](https://github.com/astral-sh/setup-uv-benchmarks/pull/4) | 19 |
1820 / 1820 / 436 MB | 9.9-21.1 / 10.5-11.0 / 5.0-7.0 s | 0 / 4 |
| CPU PyTorch |
[#5](https://github.com/astral-sh/setup-uv-benchmarks/pull/5) | 14 | 182
/ 182 / 1 MB | 3.0-6.0 / 3.6-4.0 / 5.7-6.4 s | 0 / 6 |
| CPU-PyTorch ML |
[#6](https://github.com/astral-sh/setup-uv-benchmarks/pull/6) | 137 |
346 / 346 / 10 MB | 7.4-18.0 / 8.8-8.9 / 9.7-11.9 s | 0 / 20 |
| CUDA PyTorch |
[#7](https://github.com/astral-sh/setup-uv-benchmarks/pull/7) | 201 |
2316 / 2315 / 16 MB | 30.2-67.9 / 31.0-63.6 / 33.3-36.7 s | 0 / 40 |
The CUDA workload intentionally reproduces the original `torch==2.1.1`
example. Keeping wheels again produces a ~2.3 GB Actions cache. Across
nine warm runs, restoring that cache ranged from slightly faster than
re-downloading to roughly twice as slow; pruning consistently
re-downloaded 40 distributions in ~33-37 seconds ([original
runs](https://github.com/astral-sh/setup-uv-benchmarks/actions/runs/29750292738),
[additional
runs](https://github.com/astral-sh/setup-uv-benchmarks/actions/runs/29761705492)).
I also tried running `uv cache prune --force` without `--ci` across
every workload, to see if it provided a useful middle ground. It did not
meaningfully reduce any of the caches: plain prune took 11-21 ms and
left the extracted cache and file count unchanged, including PySpark. On
these fresh caches, there are no dangling entries to remove; without
`--ci`, the pre-built wheels and unpacked source/build artifacts are
retained. The per-workload runs are linked in the table above.
So the original motivation still holds for very large CUDA or
source-heavy workloads, but it is not representative of the common case.
For smaller workloads, keeping pre-built wheels is generally faster and
avoids repeated PyPI traffic. This changes the default accordingly,
while retaining `prune-cache: true` as an opt-in for workloads where the
smaller cache is worthwhile.
Closes https://github.com/astral-sh/setup-uv/issues/745.
## Summary
- strip PEP 508 environment markers before extracting uv versions from
dependency entries
- cover dependency-group pins with and without whitespace before the
marker
- cover requirements-style pins with markers
Fixes#920
## Validation
- npm ci --ignore-scripts
- npm run all
Refs: pi-session 019f316a-4108-7975-892f-ee5bf8abc7c3
## Summary
- URL-encode the Python version component before adding it to the cache
key
- URL-encode the user-provided cache suffix for the same reason
- Add cache key tests for Python ranges, comma-containing suffixes, and
unchanged simple inputs
Fixes#914
Refs: pi-session 019f3164-85e7-7817-bffd-501d89b3a1fd
## Tests
- npm run all
Adds `uv.lock` as a supported `version-file` source. When `uv` is locked
as a
dependency in `uv.lock`, the action now installs the exact pinned
version,
closing the gap reported in #682.
This is useful for deterministic CI: the same uv version is used until
the
lockfile is updated, which avoids "CI worked yesterday, fails today"
drift and
reduces supply-chain exposure from auto-installing the latest release.
The implementation mirrors the existing `version-file` parsers — a new
`uv.lock`
entry in the parser registry reads the `[[package]]` whose `name = "uv"`
and
returns its locked `version`. Scoped to explicit `version-file:
uv.lock`;
workspace auto-detection is left as a possible follow-up to avoid
precedence
ambiguity with `uv.toml` / `pyproject.toml`.
Validation (local, Node 23; dist build is esbuild-deterministic):
- `npm run all` → build clean, biome clean, package clean, jest 77/77
- New tests: 3 unit (`uv-lock-file.test.ts`) + 1 integration — exact pin
resolves
through the full pipeline (`uv.lock` → `0.8.17`)
- dist rebuilt + committed (single bundle, no spurious churn)
related: #682
## Summary
Add a new boolean input `download-from-astral-mirror` (default: `true`)
that controls whether uv is downloaded from the Astral mirror or
directly from GitHub Releases.
When set to `false`, the mirror rewrite is skipped entirely and the
download goes straight to GitHub Releases.
Closes: #870
This PR tries fetching the uv artifact from `releases.astral.sh` by
default, only in cases where the artifact would otherwise have come from
`https://github.com/astral-sh/uv/releases/download/`. The checksums are
supposed to be the same for the mirror, and can still come from
`raw.githubusercontent.com/astral-sh/versions`. If the download fails,
we fall back to the original URL.
This avoids hitting GitHub's Releases API which is prone to rate
limiting. As far as I can tell, together with
https://github.com/astral-sh/setup-uv/pull/802 this PR makes a github
token entirely unnecessary for this action.
Towards https://github.com/astral-sh/uv/issues/18503.
The test-no-python-version test was failing because hatchling's
dependency on pathspec was incompatible with Python 3.9,
causing a TypeError during the build process.
Fixed by switching from hatchling to uv_build backend
(0.9.22-0.10.0 range) which is fully compatible with
Python 3.9. The uv.lock file is updated to reflect the
new build backend and latest compatible versions of dependencies.
setup-uv gets confused when there are backslashes in `requirements.txt`.
This changes the regex to ignore backslashes.
---------
Co-authored-by: axm2 <>
1. If defined use version input
2. If defined use uv-file input
3. If defined use pyproject-file input
4. Search for required-version in uv.toml in repo root
5. Search for required-version in pyproject.toml in repo root
6. Use latest
Closes: #215
Zsolt DollensteinandGitHub
Danny WardandGitHub
Zanie BlueandGitHub
William WoodruffandGitHub
Charlie MarshandGitHub
somazandGitHub
Kevin StillhammerandGitHub
