# uv cache clean vs prune vs clean torch: State Management Differences Explained

> Understand the state management differences between uv cache prune, uv cache clean torch, and uv cache clean. Learn which command best suits your needs for effective cache management.

- Repository: [Th3Unknovvn/uv-install-torch](https://github.com/baonguyen6742/uv-install-torch)
- Tags: deep-dive
- Published: 2026-02-26

---

**`uv cache prune` removes unreferenced cache entries while keeping needed wheels, `uv cache clean torch` deletes only PyTorch-related artifacts, and `uv cache clean` wipes the entire cache directory requiring full re-download.**

When managing PyTorch installations with **uv**, understanding cache state management is critical for resolving corrupted packages and CUDA version conflicts. The repository `baonguyen6742/uv-install-torch` demonstrates a tiered approach to cache recovery using three distinct commands that vary in scope and destructiveness. Each command serves a specific purpose in maintaining environment integrity without unnecessary network overhead.

## How uv Cache State Management Works

The **uv** package manager maintains a local cache of downloaded wheels and extracted archives to accelerate subsequent installations. This cache persists across virtual environments and projects, meaning a wheel downloaded for one project remains available for others. However, when switching between CPU and GPU builds of PyTorch or upgrading CUDA versions (e.g., from CUDA 12.1 to 12.4), cached artifacts may become incompatible or corrupted, necessitating targeted cleanup strategies.

## The Three-Tier Cache Recovery Strategy

The repository documentation in [`README.md`](https://github.com/baonguyen6742/uv-install-torch/blob/main/README.md) (lines 66-69) outlines a progressive approach to cache management, moving from least to most destructive interventions.

### uv cache prune: Surgical Cleanup of Orphaned Entries

The `uv cache prune` command performs a **reference scan** of the cache directory, identifying and removing only those entries that are no longer referenced by any locked environment (`uv.lock` file). This command preserves wheels that are still needed by existing projects, making it the safest first-line troubleshooting step.

Use this when encountering installation failures caused by stale metadata or partially downloaded files. The operation is lightweight and avoids re-downloading valid packages.

### uv cache clean torch: Scoped Removal for PyTorch Artifacts

The `uv cache clean torch` command executes a **package-scoped deletion**, removing only cached entries associated with the `torch` package and its related wheels (including torchvision and torchaudio). This targeted approach leaves all other cached dependencies untouched, significantly reducing recovery time when only PyTorch-specific wheels are problematic.

This is the optimal choice when switching CUDA variants (e.g., `cpu` ↔ `cu124`) as defined in the repository's [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) extras, or when a specific torch build has corrupted without affecting the broader environment.

### uv cache clean: Complete Cache Reset

The `uv cache clean` command performs an **unconditional purge** of the entire cache directory, discarding every cached wheel regardless of whether it is currently referenced. Following this command, the next `uv sync` or `uv pip install` operation will re-download all dependencies from the network.

Reserve this nuclear option for scenarios where the cache structure itself is suspected to be corrupted, or after major toolchain migrations that render all existing wheels incompatible.

## Implementation in baonguyen6742/uv-install-torch

The repository structure demonstrates the complete cache management lifecycle across three key files:

- **[`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml)**: Defines the `cpu` and `cu124` optional dependencies that determine which PyTorch wheel variants are fetched and cached
- **[`README.md`](https://github.com/baonguyen6742/uv-install-torch/blob/main/README.md)**: Documents the progressive cache recovery workflow at lines 66-69
- **[`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py)**: Provides post-installation verification by importing `torch`, `torchvision`, and `torchaudio` to confirm correct wheel selection after cache operations

When the `cu124` extra is specified in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml), uv attempts to cache the CUDA 12.4-enabled torch wheels. If these specific wheels become corrupted, the tiered approach allows precise remediation without invalidating unrelated dependencies.

## Step-by-Step Cache Recovery Workflow

Follow this sequence from the repository documentation to resolve PyTorch installation issues efficiently:

1. **Attempt lightweight cleanup** to remove unreferenced entries:

   ```bash
   uv cache prune
   ```

2. **If the issue persists**, remove only PyTorch artifacts to force a fresh download of the specific wheel variant:

   ```bash
   uv cache clean torch
   ```

3. **As a last resort**, wipe the entire cache when structural corruption is suspected:

   ```bash
   uv cache clean
   ```

After any cache operation, verify installation integrity using the repository's check script:

```bash
uv run python main.py

```

## Summary

- **`uv cache prune`** deletes only unreferenced cache entries, preserving needed wheels and minimizing re-downloads
- **`uv cache clean torch`** removes only PyTorch-specific artifacts, ideal for CUDA variant switches without affecting other dependencies
- **`uv cache clean`** wipes the entire cache directory, requiring complete re-download but guaranteeing a pristine state
- The repository `baonguyen6742/uv-install-torch` implements these commands in [`README.md`](https://github.com/baonguyen6742/uv-install-torch/blob/main/README.md) to manage state transitions between CPU and GPU PyTorch builds
- Always verify installations using [`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py) after cache manipulation to ensure the correct wheel variant is active

## Frequently Asked Questions

### When should I use uv cache clean torch instead of uv cache clean?

Use `uv cache clean torch` when only the PyTorch installation is problematic—such as when switching between CPU and CUDA variants defined in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) or when a specific torch wheel is corrupted. This preserves your cache of unrelated dependencies like NumPy or Pillow, whereas `uv cache clean` forces re-download of everything.

### Does uv cache prune delete packages I currently need?

No, `uv cache prune` specifically scans for entries that are no longer referenced by any `uv.lock` file in your projects. It preserves wheels that are actively needed, making it the safest initial troubleshooting step that won't trigger unnecessary network requests.

### Why does switching CUDA versions require cache cleaning?

PyTorch wheels are platform-specific and compiled against specific CUDA versions. When you switch from CUDA 12.1 to 12.4 (or from `cpu` to `cu124`) as configured in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml), the existing cached wheels become incompatible with your new requirements. Cleaning the torch-specific cache ensures uv downloads the correct architecture-specific build on the next sync.

### How do I verify that cache cleaning resolved my installation issue?

After executing any cache command, run `uv sync` to reinstall dependencies, then execute the verification script in the repository:

```bash
uv run python main.py

```

This script imports torch and its companion libraries, confirming that the correct wheel variant is loaded and CUDA is accessible (if using GPU extras).