# How to Manage uv's Cache Size


[uv](https://pydevtools.com/handbook/reference/uv.md) 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](https://pydevtools.com/handbook/how-to/how-to-install-uv.md)

## Check the cache size

```console
$ uv cache size --human
31.1GiB
```

To see where the cache lives:

```bash
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:

```bash
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:

```bash
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

```bash
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.

> [!WARNING]
> Do not delete files inside the cache directory manually. Use `uv cache clean` or `uv cache prune`, which handle internal bookkeeping safely. Modifying the cache directly can leave it in an inconsistent state.

## 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:

```bash
export UV_CACHE_DIR=/Volumes/external/uv-cache
```

Add the line to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`) so it persists.

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

Restart your terminal for the change to take effect.

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](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md) 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:

```bash
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.