The caching system provides a global cache that stores HTTP responses, package metadata, downloaded artifacts, and built wheels using content-addressed storage. All uv operations share this cache, which minimizes redundant network requests and rebuild operations. The cache is persistent on disk with sophisticated invalidation strategies based on HTTP caching policies (RFC 7234) and content hashes.
The cache location defaults to ~/.cache/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows crates/uv-cache/src/cli.rs24-31 Users can manage the cache with commands like uv cache clean docs/concepts/cache.md140-142 uv cache prune docs/concepts/cache.md143-146 and uv cache dir crates/uv-cache/src/cli.rs29
Sources:
The global cache consists of multiple layers, each responsible for caching different types of data. All cache entries are stored under a single root directory and organized into buckets.
Global Cache Architecture
The Cache struct is the main abstraction for interacting with the filesystem crates/uv-cache/src/lib.rs164-177 To ensure thread safety and prevent corruption during concurrent uv processes, the system uses file-based locks:
uv cache clean and uv cache prune operations crates/uv-cache/src/lib.rs208-237Sources:
The RegistryClient integrates with the CachedClient to handle network requests with RFC 7234 compliant caching crates/uv-client/src/registry_client.rs195-198
The system supports several CacheControl modes crates/uv-client/src/cached_client.rs172-181:
None: Respects standard cache-control headers.MustRevalidate: Forces a max-age=0 check.AllowStale: Permits using expired entries, useful for offline mode.Override: Explicitly sets a header value.Cached network responses (like Simple API results) are serialized using rkyv for performance or Serde (via rmp-serde) for compatibility crates/uv-client/src/cached_client.rs56-95 The Cacheable trait generalizes this process crates/uv-client/src/cached_client.rs32-46
Sources:
uv uses a sophisticated CacheInfo mechanism to determine if a cached artifact (like a built wheel from a local directory) is still valid crates/uv-cache-info/src/cache_info.rs22-42
The CacheInfo struct tracks several metadata points crates/uv-cache-info/src/cache_info.rs26-42:
ctime (creation time) of relevant files (e.g., pyproject.toml, setup.py, setup.cfg) crates/uv-cache-info/src/cache_info.rs27-31Users can customize invalidation by adding tool.uv.cache-keys to their pyproject.toml docs/concepts/cache.md48-58 This supports:
src) is created or removed docs/concepts/cache.md104-110Sources:
The uv cache clean command removes entries from the cache. It can target the entire cache or specific packages docs/concepts/cache.md140-142
PackageName. The CleaningPackageReporter provides progress updates during this operation.uv cache prune removes "dangling" or unused entries docs/concepts/cache.md143-146
uv tool run docs/concepts/cache.md143-146Sources:
The CacheEntry struct represents a specific file within the cache, while CacheShard represents a subdirectory crates/uv-cache/src/lib.rs53 crates/uv-cache/src/lib.rs115 These structs provide methods for path manipulation and acquiring file locks crates/uv-cache/src/lib.rs55-104 crates/uv-cache/src/lib.rs119-138
The DistributionDatabase uses the cache to convert distributions to wheels or metadata crates/uv-distribution/src/distribution_database.rs43-51 It manages downloads via a semaphore and uses ManagedClient to interface with the RegistryClient crates/uv-distribution/src/distribution_database.rs63-74
Sources:
The following diagram maps high-level caching concepts to the specific Rust structs and functions that implement them.
Code Entity Space Mapping
Sources:
Refresh this wiki