uv --no-cache and UV_NO_CACHE in CI
uv --no-cache runs without reading or writing the cache, forcing a clean fetch for that invocation.
Most CI wants the cache on, but --no-cache (or --refresh) is the tool for a clean-room reproducibility check or to sidestep a corrupted cache entry.
What it does
uv --no-cache disables the cache entirely for the command: nothing is read from it and nothing is written to it. The related --refresh keeps the cache but ignores existing entries and re-fetches, while --refresh-package targets one package.
Common usage
uv sync --no-cache
uv pip install --no-cache requests
uv sync --refresh
uv pip install --refresh-package numpy numpy
UV_NO_CACHE=1 uv syncOptions
| Flag / Env | What it does |
|---|---|
| --no-cache | Do not read or write the cache for this run |
| --refresh | Ignore cached entries and re-fetch everything |
| --refresh-package <name> | Re-fetch just one package |
| UV_NO_CACHE | Env var equivalent of --no-cache |
In CI
Leave the cache on for speed; reach for --no-cache only in a job whose purpose is to prove a clean fetch works, or to bypass a poisoned cache while you investigate. To fix a single stale wheel without nuking everything, prefer --refresh-package over --no-cache.
Common errors in CI
Disabling the cache makes network failures more visible: "error: Failed to fetch ... operating system error" surfaces when a run that previously hit cache now must reach the index. If --no-cache "fixes" an intermittent failure, the underlying cause is usually a corrupted cache entry; run uv cache clean and re-enable caching.