uv cache clean

Clear the cache, removing all entries or those linked to specific packages

uv cache clean

Clear the cache, removing all entries or those linked to specific packages.

Usage

uv cache clean [OPTIONS] [PACKAGE]...

Description

Remove entries from the uv cache. Can remove all cache entries or only those related to specific packages.

The cache stores:

• Downloaded wheels and source distributions
• Wheels built from source distributions
• Git repository clones
• Extracted source distributions

By default, uv cache clean will block until no process is reading the cache. Use --force to bypass this check.

Arguments

[PACKAGE]...

The packages to remove from the cache.

If no packages are specified, all cache entries are removed.

# Remove all cache entries
uv cache clean

# Remove cache for specific package
uv cache clean requests

# Remove cache for multiple packages
uv cache clean numpy pandas matplotlib

Options

--force

Force removal of the cache, ignoring in-use checks.

By default, uv cache clean will block until no process is reading the cache. When --force is used, uv cache clean will proceed without taking a lock.

uv cache clean --force

WARNING: Using --force while other uv processes are running may lead to cache corruption or unexpected behavior.

Examples

Remove all cache entries

uv cache clean

This will remove all cached packages, wheels, and source distributions.

Expected output:

Cleared cache entries
Removed 2.5 GiB from cache

Remove cache for a specific package

uv cache clean numpy

Removes all cached versions and builds of numpy.

Expected output:

Removed numpy from cache
Removed 125 MiB from cache

Remove cache for multiple packages

uv cache clean requests urllib3 certifi

Removes cache entries for multiple packages at once.

Force clean without waiting

uv cache clean --force

Immediately clears the cache without waiting for locks.

Use with caution if other uv processes might be running.

Clean specific package with force

uv cache clean pandas --force

Use cases

Free up disk space

The cache can grow large over time. Clean it to reclaim space:

# Check cache size first
uv cache size

# Clean all cache
uv cache clean

Remove corrupted cache entries

If you encounter cache-related errors:

# Clean specific problematic package
uv cache clean problematic-package

# Or clean entire cache
uv cache clean

Reset after configuration changes

After changing Python versions or build settings:

uv cache clean

Clean before migration

Before moving or backing up your cache:

# Clean everything
uv cache clean

# Then move cache directory if needed
mv ~/.cache/uv ~/.cache/uv.backup

CI/CD cache maintenance

In continuous integration, selectively clean cache:

# Clean specific packages that update frequently
uv cache clean mypackage

# Or use prune for more granular control
uv cache prune

Behavior details

What gets removed

When cleaning a package:

• All downloaded wheels for that package
• All source distributions for that package
• All locally built wheels for that package
• Git clones if the package is from a Git repository

When cleaning all packages:

• The entire cache directory is cleared
• Fresh downloads will be required for all packages

Locking behavior

By default, uv cache clean waits for all other uv processes to finish:

# This will wait if another uv command is running
uv cache clean

With --force, the lock is bypassed:

# This proceeds immediately
uv cache clean --force

Performance impact

After cleaning the cache:

• First installation of packages will be slower (must download)
• Subsequent installations will rebuild the cache
• Building from source will be slower (no cached wheels)

Cache location

The cache is typically located at:

• Unix/macOS: ~/.cache/uv or $XDG_CACHE_HOME/uv
• Windows: %LOCALAPPDATA%\uv\cache

To see your cache location:

uv cache dir

Comparison with other cache commands

uv cache clean vs uv cache prune

• uv cache clean: Removes all entries or specific packages
• uv cache prune: Removes unreachable entries (more granular)

# Remove everything for a package
uv cache clean numpy

# Remove only unreachable entries
uv cache prune

uv cache clean vs rm -rf

Don’t manually delete cache directories:

# Wrong: Can cause corruption
rm -rf ~/.cache/uv

# Right: Use uv's command
uv cache clean

Related commands

• uv cache prune - Remove unreachable cache entries
• uv cache dir - Show the cache directory
• uv cache size - Show the cache size

Notes

• Cleaning the cache is safe but will slow down subsequent installations
• The cache automatically manages its size and contents
• Use uv cache prune for more selective cleaning
• --force should be used carefully to avoid cache corruption
• After cleaning, uv will rebuild the cache as packages are installed
• The cache is global and shared across all projects