> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv cache prune

> Prune all unreachable objects from the cache

# uv cache prune

Prune all unreachable objects from the cache.

## Usage

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
uv cache prune
```

Expected output:

```
Pruning cache...
Removed 512 MiB from cache
Cache size: 1.8 GiB
```

### Prune for CI environments

```bash theme={null}
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

```bash theme={null}
uv cache prune --force
```

Immediately prunes the cache without waiting for locks.

### Combine CI mode with force

```bash theme={null}
uv cache prune --ci --force
```

## Use cases

### CI/CD cache optimization

In GitHub Actions or similar CI systems:

```yaml theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
uv cache prune
```

This removes cache entries no longer needed.

### Disk space management

When running low on disk space:

```bash theme={null}
# 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:

```yaml theme={null}
- 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`:

```yaml theme={null}
- 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
```

## Related commands

* [`uv cache clean`](/cli/cache-clean) - Remove all cache entries or specific packages
* [`uv cache dir`](/cli/cache-dir) - Show the cache directory
* [`uv cache size`](/cli/cache-size) - Show the cache size

## 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