Developer storage

uv Cache Taking Up Space on Mac? What It Is and How to Clean It Safely

You scan your Mac because storage is getting low. One of the biggest folders is ~/.cache/uv. Here is what creates it, why uvx and MCP servers make it grow, and how to clean it safely.

Diskfern Team7 min readUpdated October 19, 2026

Short answer

The uv cache (~/.cache/uv) stores downloaded Python wheels, metadata, and disposable environments created by uv and uvx. Do not delete the folder manually through shell removal commands. First check its size with 'uv cache size -H', then safely reclaim unused space with 'uv cache prune'. If you need a full reset, use 'uv cache clean'.

Diagram of uv cache on Mac showing isolated tool environments, cached wheels, and copy-on-write clones. — A conceptual view of uv's caching layer, tool environments, and APFS physical storage behavior.

Why is there a uv folder on my Mac?

You may be using uv without realizing it. Modern Python workflows, AI coding assistants (like Cursor, Claude Code, or VS Code extensions), and Model Context Protocol (MCP) servers frequently invoke tools via uvx.

uvx is an alias for uv tool run. It executes a CLI tool in an isolated, temporary virtual environment without permanently installing it into your global Python environment.

When an AI assistant or developer script executes an MCP server via uvx some-mcp-server, uv automatically downloads the required Python packages and builds a cached environment. Astral confirms that environments created by uvx are stored directly in uv's cache directory and treated as disposable.

The execution chain typically looks like: AI coding tool -> MCP server -> uvx -> Python dependencies -> ~/.cache/uv.

Where is the uv cache on macOS?

By default on macOS, uv stores its cache inside your user home directory at ~/.cache/uv. However, custom configurations and environment variables can alter this path.

Rather than guessing, run uv cache dir in Terminal to output the exact active directory on your system. When no custom configuration is set, Astral documents $HOME/.cache/uv as the standard Unix and macOS default.

Before modifying or deleting anything, measure both the cache directory and your Mac's current disk headroom using Terminal:

$uv cache dir && uv cache size -H && df -h /

Record your numbers before cleaning so you can verify how much physical storage is actually restored to your Mac.

Why a 20 GB cache does not always mean 20 GB freed

Folder size, physical block allocation, and immediately reclaimed space can be three different numbers on macOS due to APFS copy-on-write cloning and hardlinks.

macOS formats drives using APFS (Apple File System). APFS supports copy-on-write clones, which allow multiple files to share the same physical storage blocks until one of them is modified. Similarly, uv uses hardlinks and clones whenever possible to avoid duplicate copies of identical packages across environments.

If an active project's virtual environment shares blocks with a cached wheel, deleting the cache entry unlinks uv's reference, but macOS keeps the physical blocks allocated for the project. Astral documents a preview feature in uv designed to calculate physical disk usage more accurately across APFS links.

Understanding uv storage and cleanup options
What you found	Recommended action	Result
Large ~/.cache/uv directory	Run `uv cache prune`	Removes unreferenced, stale cache entries.
Troublesome package build	Run `uv cache clean <package>`	Clears cache for that single package only.
Need maximum space recovery	Run `uv cache clean`	Wipes cache; packages redownload on next launch.
Unused installed CLI tool	Run `uv tool uninstall <tool>`	Removes tool executable and its environment.
Old project virtualenv	Inspect project folder first	Rebuilding environment requires uv sync / venv.
Cache shrunk but free space unchanged	Check active APFS clones	Shared blocks remain until other references close.

What is inside the uv cache?

The uv cache contains far more than raw wheel archives. It is a structured performance layer designed to accelerate repetitive developer workflows.

Built wheels and compiled binary artifacts.
Downloaded source archives and distribution files.
Package metadata queries and index HTTP responses.
Temporary virtual environments created dynamically by uvx.
Extracted package trees ready for fast hardlinking.

Because everything in the cache is reproducible from upstream package repositories, it is safe to prune or clear. It contains no project source code, local documents, or irreplaceable configuration files.

Start with uv cache prune

For regular maintenance, uv cache prune is the recommended first step. It selectively removes obsolete and unreferenced cache entries without wiping your active tool environments.

Unlike a complete clean, pruning keeps active cached wheels so your next command doesn't need to download packages from PyPI over the internet. Run:

$uv cache prune

After pruning, re-check your cache size and free disk space to see the result:

$uv cache size -H && df -h /

Close AI coding tools before pruning

Before cleaning the cache, quit Claude Code, Cursor, VS Code, or any terminal running background MCP servers.

If an active process is executing an MCP tool through uvx, uv locks the relevant environment. Forcing deletions while a daemon is reading files can cause file-lock errors or leave corrupted temporary directories.

Exiting the editor or stopping the MCP server unlocks all file descriptors so uv can cleanly delete expired files.

When should you use uv cache clean?

uv cache clean is a comprehensive reset. It removes all cached data, wheels, and tool environments across the board.

Use full cache cleaning when you need to reclaim maximum disk space immediately, or when a cached wheel has become corrupted. Note that subsequent runs will require internet access to redownload dependencies:

$uv cache clean

If you only have issues with one specific package, you can clean it selectively without affecting the rest of your cache:

$uv cache clean ruff

Why does the cache grow again after cleaning it?

A cache is designed to repopulate. If you clean ~/.cache/uv and then immediately open an AI coding editor that launches three MCP servers, uvx will immediately download those packages again.

This is expected behavior. If you want to permanently keep your storage footprint low, review which MCP servers and Python tools your coding apps are configured to launch, rather than fighting the cache itself.

uv may use storage in other locations too

Cleaning ~/.cache/uv does not affect standalone virtual environments or globally installed tools.

Python projects frequently maintain an isolated .venv directory inside the project root. Furthermore, tools installed globally via uv tool install reside in a dedicated tool directory. You can inspect and clean them with:

$uv tool dir && uv tool list

Astral's storage documentation explicitly separates project virtualenvs, persistent tools, managed Python binaries, and temporary caches.

What you should avoid doing

Avoid deleting ~/.cache/uv directly with recursive file removal commands. While it may seem like a quick shortcut, manual deletion bypasses uv's locking mechanism and can break running instances.

Similarly, never blindly delete .venv folders or files containing the word 'cache' without checking their parent directory. Always verify what created a directory before deciding how to remove it.

Recommended uv cleanup commands

Use uv's official CLI commands to inspect and clean your cache safely without breaking project virtual environments.

1
Quit active coding assistants and MCP server sessions.
Ensures file descriptors in ~/.cache/uv are not held open.
2
Check your current cache path and allocated size.
$uv cache dir && uv cache size -H
Provides your baseline measurement.
3
Prune unreferenced and stale cache entries first.
$uv cache prune
Reclaims unused disk space while keeping active wheels cached.
4
If you need a complete reset, clear the full cache.
$uv cache clean
Removes all cached wheels and uvx tool environments; requires redownloading on next run.
5
Check for old installed tools that you no longer need.
$uv tool list
Use 'uv tool uninstall <tool>' to remove persistent CLI tools.

The Diskfern way

How Diskfern helps

Find developer cache hotspots visually

Scan your Mac with Diskfern to see how ~/.cache/uv compares with Xcode, Docker, and project folders.
Use Quick Look to inspect folder contents, modification dates, and disk usage.
Run uv's supported prune or clean commands directly in Terminal.
Rescan with Diskfern to verify that your free space has updated accurately.

Finding and reviewing is free. Moving items to the Trash from Diskfern is part of Pro.

Scan your Mac free

Questions

Is ~/.cache/uv safe to delete?

Yes, the contents of ~/.cache/uv are disposable and can be recreated automatically. However, you should always use 'uv cache prune' or 'uv cache clean' rather than manually deleting the directory.

What is the difference between uv cache prune and uv cache clean?

'uv cache prune' removes obsolete and unreferenced cache entries while preserving reusable wheels. 'uv cache clean' removes all cached data, requiring uv to redownload dependencies the next time they are used.

Can MCP servers cause the uv cache to grow large?

Yes. When an AI tool runs an MCP server through uvx, uv creates an isolated virtual environment inside its cache. If you test many MCP servers, each tool environment adds to the cache.

Will clearing the uv cache break my Python projects?

No. Your project source code and existing .venv virtual environments remain untouched. The only impact is that your next uv or uvx run will need to download packages from PyPI again.

Where else does uv store files on macOS?

uv stores persistent tool environments in the directory shown by 'uv tool dir', and downloads managed Python versions to the directory shown by 'uv python dir'. These are kept separate from ~/.cache/uv.