diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index 2f2b689a8f7b..4188977321db 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -22,13 +22,39 @@ uv's cache is designed to be thread-safe and append-only, and thus robust to mul readers and writers. uv applies a file-based lock to the target virtual environment when installing, to avoid concurrent modifications across processes. -Note that it's _not_ safe to modify the uv cache directly (e.g., `uv cache clean`) while other uv -commands are running, and _never_ safe to modify the cache directly (e.g., by removing a file or -directory). +Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands are +running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory). If you're running into caching issues, uv includes a few escape hatches: - To force uv to revalidate cached data for all dependencies, run `uv pip install --refresh ...`. - To force uv to revalidate cached data for a specific dependency, run, e.g., `uv pip install --refresh-package flask ...`. - To force uv to ignore existing installed versions, run `uv pip install --reinstall ...`. -- To clear the global cache entirely, run `uv cache clean`. + +## Clearing the cache + +uv provides a few different mechanisms for removing entries from the cache: + +- `uv cache clean` removes _all_ cache entries from the cache directory, clearing it out entirely. +- `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating the cache for a + single or finite set of packages. +- `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain entries created in + previous uv versions that are no longer necessary and can be safely removed. `uv cache prune` is safe to + run periodically, to keep the cache directory clean. + +## Caching in continuous integration + +It's common to cache package installation artifacts in continuous integration environments (like GitHub Actions or +GitLab CI) to speed up subsequent runs. + +By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, +to enable high-performance package installation. + +However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out +that it's often faster to _omit_ pre-built wheels from the cache (and instead re-download them from the registry on each +run). On the other hand, caching wheels that are built from source tends to be worthwhile, since the wheel building +process can be expensive, especially for extension modules. + +To support this caching strategy, uv provides a `uv cache prune --ci` command, which removes all pre-built wheels from +the cache but retains any wheels that were built from source. We recommend running `uv cache prune --ci` at the end of +your continuous integration job to ensure maximum cache efficiency.