You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 47a7f4f
Browse filesBrowse the repository at this point in the historyBrowse files
## Summary
This changes the default for `prune-cache` from `true` to `false`,
motivated by [#745](#745).
Users that want the existing behavior can continue to set `prune-cache:
true` explicitly.
Some history: I originally added [`uv cache prune
--ci`](astral-sh/uv#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](actions/setup-python#822 (comment))).
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](#745 (comment))
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](astral-sh/setup-uv-benchmarks#1) |
19 | 6 / 6 / 2 MB | 0.3-0.4 / 0.3 / 0.4-0.5 s | 0 / 2 |
| Web | [#2](astral-sh/setup-uv-benchmarks#2) |
65 | 43 / 43 / 7 MB | 0.6-1.0 / 0.5-0.6 / 1.5-1.7 s | 0 / 6 |
| Scientific |
[#3](astral-sh/setup-uv-benchmarks#3) | 118 |
586 / 586 / 8 MB | 8.2-16.0 / 7.0-8.2 / 8.9-12.1 s | 0 / 19 |
| PySpark |
[#4](astral-sh/setup-uv-benchmarks#4) | 19 |
1820 / 1820 / 436 MB | 9.9-21.1 / 10.5-11.0 / 5.0-7.0 s | 0 / 4 |
| CPU PyTorch |
[#5](astral-sh/setup-uv-benchmarks#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](astral-sh/setup-uv-benchmarks#6) | 137 |
346 / 346 / 10 MB | 7.4-18.0 / 8.8-8.9 / 9.7-11.9 s | 0 / 20 |
| CUDA PyTorch |
[#7](astral-sh/setup-uv-benchmarks#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#745.
Copy file name to clipboardExpand all lines: docs/caching.md
+13-14Lines changed: 13 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,8 +33,8 @@ The computed cache key is available as the `cache-key` output:
33
33
## Enable caching
34
34
35
35
> [!NOTE]
36
-
> The cache is pruned before it is uploaded to the GitHub Actions cache. This can lead to
37
-
> a small or empty cache. See [Disable cache pruning](#disable-cache-pruning) for more details.
36
+
> The entire uv cache is uploaded to the GitHub Actions cache by default. To reduce the cache size,
37
+
> see [Enable cache pruning](#enable-cache-pruning).
38
38
39
39
If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
40
40
the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
@@ -173,30 +173,29 @@ It defaults to `setup-uv-cache` in the `TMP` dir, `D:\a\_temp\setup-uv-cache` on
173
173
cache-local-path: "/path/to/cache"
174
174
```
175
175
176
-
## Disable cache pruning
176
+
## Enable cache pruning
177
177
178
-
By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any
179
-
wheels that were built from source. On GitHub-hosted runners, it's typically faster to omit those
180
-
pre-built wheels from the cache (and instead re-download them from the registry on each run).
181
-
However, on self-hosted or local runners, preserving the cache may be more efficient. See
182
-
the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration) for
183
-
more information.
178
+
By default, the entire uv cache is persisted across runs. On GitHub-hosted runners, it's typically
179
+
faster to prune the cache before saving it, removing pre-built wheels, but retaining any wheels that
180
+
were built from source. The pre-built wheels are then re-downloaded from the registry on each run.
181
+
See the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration)
182
+
for more information.
184
183
185
-
If you want to persist the entire cache across runs, disable cache pruning with the `prune-cache`
186
-
input.
184
+
If you want to prune the cache before saving it, enable cache pruning with the `prune-cache` input.
0 commit comments