uv Cache Clean vs Prune on Mac: Which Should You Use?

Use uv cache prune for routine removal of unused cache entries, and uv cache clean when you deliberately want a broader reset. Inspect the actual cache location first. A large project environment and a large shared package cache are separate storage problems.

If a Python workflow is functioning normally, there is little value in repeatedly discarding downloads only to fetch them again during the next install.

Find the cache your uv installation uses

uv --version
uv cache dir
uv cache --help

Open the returned location in Finder or measure that exact directory. Avoid guessing from another package manager’s path. A custom setting or environment variable may change where this installation writes.

Astral’s cache documentation describes the supported cleanup commands and warns against directly editing cache contents. Use those commands instead of removing internal cache buckets manually.

Choose the smallest operation that solves the problem

• Routine maintenance: run uv cache prune after reviewing the behavior of your installed version.
• One problematic package: use a targeted operation such as uv cache clean ruff.
• Intentional complete reset: use uv cache clean, accepting that future work may need downloads or builds.

Current documentation also notes that pruning removes centralized project environments, which are recreated when needed. If you use that feature, plan for the recreation cost rather than assuming prune only removes forgotten downloads.

Separate cleanup from dependency changes

Keep your project manifest and lockfile intact. Cache maintenance should not become an unplanned dependency upgrade. Before cleaning, record the command you normally use to reproduce the environment and confirm any private registries will still be accessible afterward.

For example, a cached private wheel may be convenient to redownload while you are on the company network and difficult to obtain during travel. Decide when to clean based on that constraint, not only the folder’s size.

Wait for active package operations

Let installs and builds finish before maintenance. If uv reports a lock or another operation in progress, investigate the owner and allow it to complete. Do not turn a routine cleanup into a race by bypassing coordination or deleting files underneath an active process.

After the cleanup, run your usual project environment setup and a representative application or test. A successful command exit proves the cache operation completed; it does not prove every project you care about remains reproducible.

Why recovered space may be smaller than expected

Package data can be linked or cloned into environments, and apparent sizes do not always translate directly into newly available blocks. Compare the cache’s size and the volume’s free space separately. Keep the measurement method consistent.

If the cache is now small but storage remains high, inspect inactive project environments using the Python environment cleanup guide. Do not delete an environment until its project can be recreated and you have identified anything stored inside it manually.

Do not confuse uv and pip caches

Different tools can maintain separate downloads. If you also use pip, review the pip cache guide rather than assuming a uv operation removed both. Finish by keeping the toolchain you use day to day working, with enough storage for its next normal build.