Skip to main content

​
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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us