Is it safe to delete uv’s cache?
- Yes, with uv’s commands. uv’s docs call the cache disposable, but say never to remove files or folders inside it by hand.
uv cache pruneanduv cache cleanare the way. - What it costs you: the next
uv syncoruv pip installdownloads and builds again, so it’s slower and needs the network. - Does it come back? Yes, as soon as uv installs anything.
- SiftMac’s verdict: Rebuilds
1. What uv caches
uv caches answers from package indexes, downloaded wheels and source distributions, wheels it built itself, and the unpacked files it installs from. Installing into an environment then comes down to placing files from the cache, which keeps repeat installs fast.
On a Mac, uv’s default link mode is clone, copy-on-write on APFS. Files in each .venv start out sharing their blocks with the cache, so environments stay intact when you clear it, and the two don’t take double the space while both exist.
- Not in the cache: Pythons from
uv python install, kept in~/.local/share/uv/python, and tools fromuv tool install, in~/.local/share/uv/tools. - If you set the link mode to
symlink, environments point into the cache instead, and uv warns thatuv cache cleanwould then break every installed package.
2. Where it is
~/.cache/uv
uv follows the XDG folder conventions on macOS too, so the cache is ~/.cache/uv unless XDG_CACHE_HOME, UV_CACHE_DIR or the cache-dir setting moves it. Ask uv to be sure:
uv cache dir
3. How big it gets
Every package version your projects installed stays until you prune or clean, so the cache grows with each project and each upgrade. uv reports its own size:
uv cache size -H
Because of the clones, a full cache and full environments together use less space than their two sizes added up.
4. How to clear it
Two commands, from gentle to complete:
uv cache pruneremoves unused entries, such as ones left by earlier uv versions, and the centralized project environments uv keeps there, which it recreates when needed. uv’s docs say it’s safe to run periodically.uv cache cleanremoves every entry.uv cache clean <package>, for exampleuv cache clean ruff, removes only that package’s entries.
uv cache prune
uv cache clean
Run them while no other uv command is working. uv locks the cache while it changes it and waits up to five minutes for other uv processes; --force skips that wait, and is only safe when nothing else is using the cache.
5. What happens afterwards
- Existing
.venvfolders keep working, because their files are clones rather than links into the cache, unless you chose symlink mode. - The next
uv sync,uv runoruv pip installdownloads again, and packages without a wheel for your Mac are built again. uv.lockkeeps every version the same.- Tools you run with
uvxare fetched again the first time you use them.
Questions
Can I delete ~/.cache/uv in Finder?
Use uv cache clean instead. uv’s docs say it’s never safe to modify the cache directly, for example by removing a file or folder inside it, while the command respects uv’s lock on it.
What’s the difference between uv cache prune and uv cache clean?
Prune keeps what’s still useful and drops the rest; clean removes everything, or everything for one package. For CI, uv cache prune --ci removes pre-built wheels and unzipped source distributions but keeps wheels built from source, the slow part to recreate.
Does clearing uv’s cache remove the Pythons uv installed?
No. They live in ~/.local/share/uv/python; remove versions you no longer need with uv python uninstall.
Will my virtual environments break?
Not with uv’s default clone mode on a Mac: each environment’s files are independent copies that just started out sharing blocks. Environments made with the symlink link mode are the exception.
How SiftMac handles it. SiftMac doesn’t clear ~/.cache/uv; its space map shows how big ~/.cache is and notes that the tool caches in it download again, and uv cache clean does the clearing. When Developer files lists an old project’s .venv, the size shown leaves out blocks the environment still shares with uv’s cache. A uv folder in ~/Library/Caches, if your Mac has one, is cleared with App caches and skipped while uv is running.
Download SiftMac · scanning is free, and so is your first 2 GB of cleaning · See how it works