uv cache clean: Clear the uv Cache
uv cache clean deletes the uv cache, optionally for just one package, to reclaim space or recover from corruption.
uv cache clean is the reset button when a cached artifact goes bad or a runner runs low on disk. It removes downloaded distributions and built wheels.
What it does
uv cache clean removes entries from the uv cache directory. With no argument it clears everything; with a package name it removes only that package cache. uv cache prune (a sibling) removes only unused entries rather than the whole cache.
Common usage
uv cache clean
uv cache clean numpy
uv cache prune
uv cache prune --ciOptions
| Command / Flag | What it does |
|---|---|
| uv cache clean | Remove the entire cache |
| uv cache clean <pkg> | Remove only that package from the cache |
| uv cache prune | Remove unused cache entries, keep useful ones |
| uv cache prune --ci | Prune aggressively for CI cache uploads |
In CI
Run uv cache prune --ci at the end of a job before saving the cache: it drops pre-built wheels for the local project that are not worth caching, shrinking the uploaded cache. Reach for uv cache clean only to recover from a corrupted cache, since it discards all reuse.
Common errors in CI
"error: Failed to clear cache ... Permission denied" means the cache directory is owned by another user (common when a root container wrote it and a non-root step reads it); fix ownership or set UV_CACHE_DIR to a writable path. A "No such file or directory" on clean is harmless: the cache was already empty.