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

​
How Caching Works

uv maintains a global cache that stores:
  • Downloaded wheels from package indexes
  • Built wheels from source distributions
  • Git repository clones
  • Package metadata
  • Python installations
The cache enables near-instant installations when packages have been previously downloaded or built.

​
Dependency Caching

Caching semantics vary by dependency type:
From PyPI and other indexesuv respects HTTP caching headers:
  • Cache-Control
  • ETag
  • Last-Modified
Packages are cached based on version and metadata.

​
Cache Commands

​
Clearing the Cache

# Remove all cache entries
uv cache clean

# Remove cache entries for specific package
uv cache clean ruff

# Remove all unused cache entries
uv cache prune

clean

Removes all cache entries or entries for specific packages

prune

Removes only unused entries from previous uv versions

dir

Shows the cache directory path

​
Forcing Revalidation

Force uv to revalidate cached data: 
# Revalidate all dependencies
uv sync --refresh

# Revalidate specific package
uv sync --refresh-package ruff

# Force reinstall from cache
uv sync --reinstall
Revalidates all cached data but uses cache for unchanged packages.

​
Local Directory Dependencies

Local directory dependencies passed explicitly are always rebuilt: 
# Always rebuilds current directory
uv pip install .

​
Dynamic Metadata Caching

By default, uv rebuilds local directory dependencies only when:
  • pyproject.toml, setup.py, or setup.cfg changes
  • A src/ directory is added or removed
This heuristic may miss some changes.

​
Custom Cache Keys

Incorporate additional information into the cache key with tool.uv.cache-keys:
Rebuild on commit changes:
pyproject.toml
[tool.uv]
cache-keys = [
  { file = "pyproject.toml" },
  { git = { commit = true } }
]

​
Glob Patterns

Use globs to track multiple files:
pyproject.toml
[tool.uv]
cache-keys = [
  { file = "**/*.toml" }  # All .toml files
]
Globs can be expensive as uv may need to walk deeply nested directory structures.

​
Environment Variables

Invalidate cache on environment variable changes:
pyproject.toml
[tool.uv]
cache-keys = [
  { file = "pyproject.toml" },
  { env = "MY_BUILD_VAR" }
]

​
Directory Existence

Track directory creation/removal:
pyproject.toml
[tool.uv]
cache-keys = [
  { file = "pyproject.toml" },
  { dir = "src" }
]
The dir key only tracks directory creation/removal, not changes within the directory.

​
Always Rebuild

Force always rebuilding specific packages:
pyproject.toml
[tool.uv]
reinstall-package = ["my-package"]

​
Cache Safety

​
Concurrent Access

It’s safe to run multiple uv commands concurrently:
  • Cache is thread-safe and append-only
  • Robust to multiple concurrent readers and writers
  • File-based locks prevent concurrent environment modifications
Never modify the cache directory directly (e.g., by removing files). Always use uv commands.

​
Lock Timeouts

Cache-modifying operations block while other uv commands run: 
# Default 5-minute timeout
uv cache clean

# Override timeout
UV_LOCK_TIMEOUT=300 uv cache clean

# Force ignore lock (dangerous)
uv cache clean --force

​
Continuous Integration Caching

Optimize CI caching by storing only built wheels, not pre-built wheels.

​
CI Cache Strategy

1

Run uv commands

.github/workflows/ci.yml
- run: uv sync
- run: uv run pytest
2

Prune pre-built wheels

.github/workflows/ci.yml
- run: uv cache prune --ci
3

Cache the directory

.github/workflows/ci.yml
- uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}

​
Why Prune Pre-built Wheels?

In CI environments:
  • Re-downloading pre-built wheels is often faster than restoring from cache
  • Building from source is expensive and worth caching
  • uv cache prune --ci removes pre-built wheels but keeps built-from-source wheels
See the GitHub Actions integration guide for complete CI examples.

​
Cache Directory

uv determines the cache directory in this order:
  1. Temporary cache (if --no-cache was requested)
  2. Explicit path from:
    • --cache-dir flag
    • UV_CACHE_DIR environment variable
    • tool.uv.cache-dir in pyproject.toml
  3. System default:
    • Unix: $XDG_CACHE_HOME/uv or $HOME/.cache/uv
    • Windows: %LOCALAPPDATA%\uv\cache

​
View Cache Directory

uv cache dir

​
Custom Cache Location

# Via environment variable
export UV_CACHE_DIR=/custom/cache/path

# Via flag
uv sync --cache-dir /custom/cache/path

# Via config file
[tool.uv]
cache-dir = "/custom/cache/path"
uv always requires a cache directory. With --no-cache, uv uses a temporary cache for that invocation. Use --refresh instead to update the persistent cache.

​
Performance Considerations

For best performance, the cache directory should be on the same filesystem as Python environments. This allows uv to use hard links instead of copying files.

​
Cache Versioning

The cache is organized into versioned buckets:

Wheels

Built and downloaded wheel files

Source Distributions

Downloaded source distributions

Git Repositories

Cloned Git repositories

Metadata

Package metadata and manifests

​
Version Compatibility

Each bucket has a version number:
  • Breaking cache format changes increment the version
  • Changes within a version are forwards and backwards compatible
  • Multiple uv versions can safely share the same cache directory

​
Version Changes Example

uv 0.4.13 increased the metadata bucket version from v12 to v13:
  • uv 0.4.12 and 0.4.13 can share a cache directory
  • The cache may contain duplicate metadata entries
  • Old entries from v12 remain but are unused

​
Cleaning Old Versions

Remove unused bucket versions: 
uv cache prune
This is safe to run periodically to reclaim disk space.

​
Cache Deduplication

uv uses deduplication to minimize disk usage: On Unix systems, uv uses hard links:
  • Same file content referenced from multiple locations
  • Zero additional disk space
  • Requires cache and environment on same filesystem
For Python installations, uv uses symbolic links:
  • Points to the actual installation
  • Enables transparent upgrades
  • Links minor versions to specific patch versions

​
Fallback to Copy

When hard links aren’t available (different filesystems):
  • uv falls back to copying files
  • Slower installation
  • More disk usage

​
Cache Contents

The cache stores:

​
Package Artifacts

  • Wheels - Both downloaded and built from source
  • Source distributions - Downloaded .tar.gz, .zip files
  • Git clones - Repository checkouts at specific commits

​
Python Installations

  • Managed Python versions - Downloaded interpreters
  • Python executables - Installed to ~/.local/bin (Unix)

​
Metadata

  • Package metadata - Version info, dependencies, markers
  • Index metadata - PyPI and custom index data
  • Resolution data - Cached dependency resolutions

​
Troubleshooting

​
Cache Issues

If experiencing cache-related problems: 
# Clear cache completely
uv cache clean

# Clear specific package
uv cache clean <package-name>

# Force refresh on next install
uv sync --refresh

# Reinstall everything
uv sync --reinstall

​
Disk Space

Monitor cache size: 
# View cache directory
uv cache dir

# Check disk usage
du -sh $(uv cache dir)
Reclaim space: 
# Remove unused entries
uv cache prune

# Clear everything
uv cache clean

​
Stale Cache

For local dependencies, ensure cache keys are properly configured:
pyproject.toml
[tool.uv]
cache-keys = [
  { file = "pyproject.toml" },
  { git = { commit = true } },
  { file = "src/**/*.py" }  # Track source changes
]

Projects

Learn about project environments and how they use the cache

Dependencies

Understand how dependencies are cached

Python Versions

Learn where Python installations are cached

CI/CD Integration

Optimize caching in continuous integration

Build docs developers (and LLMs) love

Get started for freeTalk to us