Caching

uv uses aggressive caching to avoid re-downloading (and re-building) dependencies that have already been accessed in prior runs.

• Registry dependencies: Cached using HTTP headers from registries like PyPI.
• Direct URLs: Cached using URL and HTTP headers.
• Git dependencies: Cached by resolved commit hash; uv pip compile pins to commit.
• Local dependencies: Cached based on last-modified timestamp of .whl, .tar.gz, or config files (pyproject.toml, setup.py, etc.).

Cache Invalidation

• --refresh: Revalidate all cached data.
• --refresh-package <name>: Revalidate cache for a specific package.
• --reinstall: Ignore installed packages and reinstall.

Local directory installs (e.g. uv pip install .) always rebuild and reinstall.

Dynamic Metadata Cache Keys

Use [tool.uv.cache-keys] to control cache invalidation:

• Rebuild if listed files or metadata change.

Examples:

[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true } }]

Additional options:

• { file = "requirements.txt" }
• { env = "MY_ENV_VAR" }
• { dir = "src" }
• { file = "**/*.toml" } (glob support)

To force rebuild on every run:

[tool.uv]
reinstall-package = ["my-package"]

Cache Safety

• Multiple uv commands can run concurrently — cache is thread-safe.
• Never modify the cache directly or clean it while another uv command is active.

Cleaning the Cache

• uv cache clean: Remove all cache data.
• uv cache clean <package>: Remove data for a specific package.
• uv cache prune: Remove unused or outdated cache entries.
• uv cache prune --ci: CI-specific cleanup (removes prebuilt wheels but retains built wheels).

Cache Location

Priority order for setting the cache directory:

1. --no-cache: Uses temporary, per-run cache.
2. --cache-dir, UV_CACHE_DIR, or [tool.uv].cache-dir.
3. System default:
   • Linux/macOS: $XDG_CACHE_HOME/uv or $HOME/.cache/uv
   • Windows: %LOCALAPPDATA%\uv\cache

For best performance, keep cache and Python environment on the same filesystem to enable fast linking instead of file copies.

Cache Versioning

• Each cache bucket is versioned (e.g., wheels, Git repos, metadata).
• Breaking changes bump the bucket version, creating separate cache buckets.
• Cross-version compatibility:
  • Safe to share a cache between uv versions with same bucket versions.
  • New uv versions may create new buckets but won’t overwrite old ones.