How to Manage uv's Cache Size

uv keeps a copy of every package it downloads so that future installs can skip the network. The cache grows with every new package version, and on a machine with many projects or large dependencies it can reach tens of gigabytes. These commands let you inspect, shrink, or relocate it.

Prerequisites

• uv installed

Check the cache size

$ uv cache size --human
31.1GiB

To see where the cache lives:

uv cache dir

The default location is ~/.cache/uv on macOS and Linux, %LOCALAPPDATA%\uv\cache on Windows.

Prune unused entries

uv cache prune removes unused and outdated cache entries:

uv cache prune

This is the safest routine maintenance option. Run it periodically to keep the cache directory clean.

Remove entries for a specific package

To clear cached versions of one package without touching the rest:

uv cache clean torch

Packages like torch or scipy accumulate multiple gigabytes across versions. Clearing one reclaims that space while leaving the rest of the cache intact.

Clear the entire cache

uv cache clean

This removes all cached data. The next uv sync or uv run re-downloads whatever it needs. With uv’s default link modes (clone and hardlink), existing virtual environments keep working because installed files are copies of the cached originals, not references to them. If you have set UV_LINK_MODE=symlink, clearing the cache breaks any environment that was installed with symlinks.

Relocate the cache to a different drive

Set the UV_CACHE_DIR environment variable to redirect the cache. This helps when your boot drive is small but a secondary drive has space:

export UV_CACHE_DIR=/Volumes/external/uv-cache

[Environment]::SetEnvironmentVariable("UV_CACHE_DIR", "D:\uv-cache", "User")

Changing UV_CACHE_DIR does not move or remove the old cache. Run uv cache clean --cache-dir ~/.cache/uv (the old path) to reclaim that space after confirming the new location works.

uv installs packages from its cache using copy-on-write clones (macOS/Linux) or hard links (Windows). Both require the cache and the virtual environment to be on the same filesystem. If they are on different drives, uv falls back to full copies, which is slower and doubles the disk usage. Keep the cache on the same filesystem as your project directories when possible.

Skip the cache for a single command

For one-off commands where caching adds no value:

uv sync --no-cache

The --no-cache flag (or UV_NO_CACHE=1 as an environment variable) tells uv to use a temporary directory that is discarded after the command finishes. Cached packages from previous runs are not reused, so any needed downloads happen fresh.