Caching

Caching is everywhere in uv. The cache is a content-addressed on-disk store under ~/.cache/uv (Linux) or %LOCALAPPDATA%\uv\cache (Windows), divided into typed buckets.

Buckets

CacheBucket (in uv-cache) enumerates them:

• SimpleV1 — Simple-API responses per index/package.
• Wheels{N} — wheel artifacts from registries.
• SourceDistributions{N} — source-distribution metadata, builds, and built wheels.
• Builds{N} — built wheels from local sdists / paths.
• Git{N} — bare git repos and worktrees.
• Interpreter{N} — cached Python interpreter probes.
• Archive{N} — wheel decompressions.
• Environments{N} — ephemeral environments for uv run --with.

The {N} suffixes are bucket generations: bumping them invalidates the bucket on the next run, used for breaking format changes between uv versions.

Cache-info

Each cache entry carries a cache-info sidecar with HTTP cache headers, freshness markers, and timestamps. uv-cache-info provides the Timestamp wrapper used as the freshness signal.

Refresh strategies

Refresh::All(timestamp) invalidates everything older than timestamp. Refresh::None respects HTTP cache headers (max-age, etag). The --refresh and --refresh-package <name> flags map onto these.

uv cache

User-facing commands:

• uv cache dir — print the cache directory.
• uv cache clean — remove the entire cache.
• uv cache prune — remove only out-of-date or orphaned entries.

See also

• crates/uv-cache, crates/uv-cache-info, crates/uv-cache-key.