Skip to main content

​
uv cache prune

Prune all unreachable objects from the cache.

​
Usage

uv cache prune [OPTIONS]

​
Description

Remove unreachable cache entries while preserving data that may still be useful. This is a more selective alternative to uv cache clean. Pruning removes:
  • Unused package versions
  • Outdated builds
  • Orphaned cache entries
  • Pre-built wheels (when using --ci mode)
Pruning preserves:
  • Cache entries for currently installed packages
  • Recent package downloads
  • Wheels built from source (in --ci mode)
By default, uv cache prune will block until no process is reading the cache. Use --force to bypass this check.

​
Options

​
--ci

Optimize the cache for persistence in a continuous integration environment, like GitHub Actions. By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation. In some scenarios, though, persisting pre-built wheels may be undesirable. For example, in GitHub Actions, it’s faster to omit pre-built wheels from the cache and instead have re-download them on each run. However, it typically is faster to cache wheels that are built from source, since the wheel building process can be expensive, especially for extension modules. In --ci mode, uv will prune any pre-built wheels from the cache, but retain any wheels that were built from source. 
uv cache prune --ci
This is particularly useful in CI/CD pipelines to optimize cache size and restore time.

​
--force

Force removal of the cache, ignoring in-use checks. By default, uv cache prune will block until no process is reading the cache. When --force is used, uv cache prune will proceed without taking a lock. 
uv cache prune --force
WARNING: Using --force while other uv processes are running may lead to cache corruption or unexpected behavior.

​
Examples

​
Prune unreachable entries

uv cache prune
Expected output: 
Pruning cache...
Removed 512 MiB from cache
Cache size: 1.8 GiB

​
Prune for CI environments

uv cache prune --ci
Removes pre-built wheels but keeps wheels built from source. Expected output: 
Pruning cache for CI...
Removed 1.2 GiB of pre-built wheels
Retained 600 MiB of source-built wheels
Cache size: 600 MiB

​
Force prune without waiting

uv cache prune --force
Immediately prunes the cache without waiting for locks.

​
Combine CI mode with force

uv cache prune --ci --force

​
Use cases

​
CI/CD cache optimization

In GitHub Actions or similar CI systems: 
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      
      - name: Cache uv
        uses: actions/cache@v4
        with:
          path: ~/.cache/uv
          key: uv-${{ runner.os }}-${{ hashFiles('**/uv.lock') }}
      
      - name: Install dependencies
        run: uv sync
      
      - name: Optimize cache for CI
        run: uv cache prune --ci
      
      - name: Run tests
        run: uv run pytest
This keeps the cache small and fast to restore.

​
Regular maintenance

Periodically prune cache to maintain optimal size: 
# Check current size
uv cache size

# Prune unreachable entries
uv cache prune

# Check size again
uv cache size

​
After project cleanup

After removing projects or changing dependencies: 
uv cache prune
This removes cache entries no longer needed.

​
Disk space management

When running low on disk space: 
# First try pruning (less aggressive)
uv cache prune

# If more space needed, clean specific packages
uv cache clean old-package

# Last resort: clean everything
uv cache clean

​
Behavior details

​
What gets pruned

Standard prune:
  • Package versions no longer referenced
  • Temporary build artifacts
  • Stale lock files
  • Orphaned cache entries
CI mode (--ci):
  • All pre-built wheels downloaded from indexes
  • Preserves wheels built from source distributions
  • Preserves source distributions

​
What gets preserved

Standard prune:
  • Packages in active virtual environments
  • Recently accessed cache entries
  • Package metadata
CI mode (--ci):
  • Wheels built from source (often contain compiled extensions)
  • Source distributions
  • Build dependencies

​
Performance considerations

After pruning:
  • Cache size is reduced
  • No impact on currently installed packages
  • Some packages may need re-downloading
CI mode benefits:
  • Smaller cache to upload/download
  • Faster CI job startup
  • Pre-built wheels download quickly anyway
  • Source-built wheels are expensive to rebuild

​
When to use prune vs clean

​
Use uv cache prune:

  • Regular maintenance
  • CI/CD optimization
  • Gradual disk space recovery
  • When you want to keep useful cache entries

​
Use uv cache clean:

  • Need maximum disk space immediately
  • Corrupted cache entries
  • Complete cache reset
  • Testing clean-slate installations

​
CI mode details

​
Why CI mode is faster

In CI environments:
  1. Download speed: CI runners typically have fast internet connections
  2. Cache overhead: Uploading/downloading large caches takes time
  3. Build cost: Building from source is expensive (compiling C extensions)
CI mode optimizes for this by:
  • Removing fast-to-download pre-built wheels
  • Keeping expensive-to-build source wheels

​
Example cache sizes

Typical project before pruning: 
Pre-built wheels: 1.5 GiB
Source-built wheels: 400 MiB
Source distributions: 200 MiB
Total: 2.1 GiB
After uv cache prune --ci: 
Pre-built wheels: 0 B
Source-built wheels: 400 MiB
Source distributions: 200 MiB
Total: 600 MiB

​
GitHub Actions example

Before optimization: 
- name: Cache uv
  uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: uv-${{ hashFiles('uv.lock') }}
# Cache restore: ~30 seconds
# Cache upload: ~30 seconds
After optimization with --ci: 
- name: Cache uv
  uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: uv-${{ hashFiles('uv.lock') }}

- run: uv sync

- name: Optimize cache
  run: uv cache prune --ci
# Cache restore: ~10 seconds
# Cache upload: ~10 seconds

​
Notes

  • Pruning is safer than cleaning (preserves useful entries)
  • --ci mode is specifically designed for continuous integration
  • Pruning does not affect currently installed packages
  • The cache will automatically repopulate as needed
  • --force should be used carefully to avoid cache corruption
  • Regular pruning can help maintain optimal cache performance
  • CI mode can significantly reduce CI/CD cache sizes and restore times

Build docs developers (and LLMs) love

Get started for freeTalk to us