uv cache dir and UV_CACHE_DIR in CI
uv cache dir prints the directory uv uses for its cache, which is the path you want to persist between CI runs.
Caching the uv cache directory is the single biggest CI speedup for uv. uv cache dir tells you exactly which path to save and restore.
What it does
uv cache dir outputs the absolute path of the active cache directory. By default it lives under the OS cache location (for example ~/.cache/uv on Linux), but UV_CACHE_DIR or --cache-dir overrides it. That directory holds downloaded distributions and built wheels.
Common usage
uv cache dir
UV_CACHE_DIR=/tmp/uv-cache uv sync
uv --cache-dir .uv-cache sync
# in a workflow, cache the path uv reportsOptions
| Setting | What it does |
|---|---|
| uv cache dir | Print the active cache directory |
| UV_CACHE_DIR | Env var that sets the cache directory |
| --cache-dir <path> | Per-command override of the cache directory |
| UV_NO_CACHE | Disable the cache entirely when set |
In CI
Set UV_CACHE_DIR to a stable path inside the workspace (so it is on the same filesystem as the environment for fast hardlinks) and cache that directory keyed on uv.lock. If the cache and target venv are on different filesystems, uv warns and falls back to copying, which is slower.
Common errors in CI
"warning: Failed to hardlink files; falling back to full copy" means UV_CACHE_DIR is on a different filesystem than the virtualenv; co-locate them or set UV_LINK_MODE=copy to silence it. A cache restored from a different OS or architecture is ignored, not reused, so jobs may seem to re-download despite a cache hit.