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

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 (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 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: Defines the cpu and cu124 optional dependencies that determine which PyTorch wheel variants are fetched and cached
• README.md: Documents the progressive cache recovery workflow at lines 66-69
• 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, 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:

   uv cache prune

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

   uv cache clean torch

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

   uv cache clean

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

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 to manage state transitions between CPU and GPU PyTorch builds
• Always verify installations using 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 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, 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:

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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}