Skip to content

Commit 47a7f4f

Browse files
Change prune-cache default to false (#967)
## 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.
1 parent 71966ef commit 47a7f4f

5 files changed

Lines changed: 18 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
100100
cache-local-path: ""
101101
102102
# Prune cache before saving
103-
prune-cache: "true"
103+
prune-cache: "false"
104104
105105
# Upload managed Python installations to the GitHub Actions cache
106106
cache-python: "false"

‎__tests__/cache/restore-cache.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,13 +62,13 @@ describe("restoreCache", () => {
6262
expect(cacheKey).toContain("-tests-3.10%2C3.11");
6363
});
6464

65-
it("keeps cache keys unchanged for exact Python versions and simple suffixes", async () => {
65+
it("uses an unpruned cache key by default", async () => {
6666
const inputs = createSetupInputs({ cacheSuffix: "tests-3.11" });
6767

6868
await restoreCache(inputs, "3.11");
6969

7070
expect(cacheKeyOutput()).toBe(
71-
"setup-uv-2-x86_64-unknown-linux-gnu-ubuntu-24.04-3.11-pruned-dependencyhash-tests-3.11",
71+
"setup-uv-2-x86_64-unknown-linux-gnu-ubuntu-24.04-3.11-dependencyhash-tests-3.11",
7272
);
7373
});
7474
});

‎__tests__/helpers/setup-inputs.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ export function createSetupInputs(
2020
ignoreEmptyWorkdir: false,
2121
ignoreNothingToCache: false,
2222
noProject: false,
23-
pruneCache: true,
23+
pruneCache: false,
2424
pythonDir: "/tmp/uv-python-dir",
2525
pythonVersion: "",
2626
quiet: false,

‎action.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ inputs:
6161
default: ""
6262
prune-cache:
6363
description: "Prune cache before saving."
64-
default: "true"
64+
default: "false"
6565
cache-python:
6666
description: "Upload managed Python installations to the Github Actions cache."
6767
default: "false"

‎docs/caching.md‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ The computed cache key is available as the `cache-key` output:
3333
## Enable caching
3434
3535
> [!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).
3838
3939
If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
4040
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
173173
cache-local-path: "/path/to/cache"
174174
```
175175

176-
## Disable cache pruning
176+
## Enable cache pruning
177177

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.
184183

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.
187185

188186
```yaml
189-
- name: Don't prune the cache before saving it
187+
- name: Prune the cache before saving it
190188
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
191189
with:
192190
enable-cache: true
193-
prune-cache: false
191+
prune-cache: true
194192
```
195193

196194
## Cache Python installs
197195

198196
By default, the Python install dir (`uv python dir` / `UV_PYTHON_INSTALL_DIR`) is not cached,
199-
for the same reason that the dependency cache is pruned.
197+
for the same reason that pruning the dependency cache can improve performance on GitHub-hosted
198+
runners.
200199
If you want to cache Python installs along with your dependencies, set the `cache-python` input to `true`.
201200

202201
Note that this only caches Python versions that uv actually installs into `UV_PYTHON_INSTALL_DIR`

0 commit comments

Comments
 (0)