uv cache dir

Show the cache directory

uv cache dir

Show the cache directory.

Usage

uv cache dir

Description

Displays the absolute path to uv’s cache directory.

By default, the cache is stored in:

• Unix/macOS: $XDG_CACHE_HOME/uv or $HOME/.cache/uv
• Windows: %LOCALAPPDATA%\uv\cache

When --no-cache is used, the cache is stored in a temporary directory and discarded when the process exits.

An alternative cache directory may be specified via:

• The cache-dir setting in configuration files
• The --cache-dir option
• The UV_CACHE_DIR environment variable

Note that it is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on.

Arguments

None.

Options

None.

Examples

Display cache directory

uv cache dir

Expected output (Unix/macOS):

/home/username/.cache/uv

Expected output (Windows):

C:\Users\Username\AppData\Local\uv\cache

Use in scripts

# Store cache directory in variable
CACHE_DIR=$(uv cache dir)
echo "Cache is at: $CACHE_DIR"

# Check cache size
du -sh "$CACHE_DIR"

# List cache contents
ls -lh "$CACHE_DIR"

Verify custom cache directory

# Set custom cache directory
export UV_CACHE_DIR=/tmp/uv-cache

# Verify it's being used
uv cache dir

Expected output:

/tmp/uv-cache

Use cases

Locate cache for inspection

Find where uv stores cached packages:

cd "$(uv cache dir)"
ls -lh

Backup cache directory

Create a backup of your cache:

CACHE_DIR=$(uv cache dir)
tar -czf uv-cache-backup.tar.gz "$CACHE_DIR"

Monitor cache size

Check cache disk usage:

# Linux/macOS
du -sh "$(uv cache dir)"

# Or use uv's built-in command
uv cache size

Verify cache location

Confirm cache is on the same filesystem as your project:

# Check cache filesystem
df "$(uv cache dir)"

# Check project filesystem
df .

# Should be on the same mount point for best performance

CI/CD cache configuration

Configure cache directory for CI systems:

# GitHub Actions
name: CI
jobs:
  test:
    steps:
      - name: Show cache location
        run: uv cache dir
      
      - name: Cache uv
        uses: actions/cache@v4
        with:
          path: ~/.cache/uv
          key: uv-${{ runner.os }}-${{ hashFiles('**/uv.lock') }}

Troubleshooting

Diagnose cache-related issues:

# Check if cache directory exists
CACHE_DIR=$(uv cache dir)
if [ -d "$CACHE_DIR" ]; then
    echo "Cache exists at: $CACHE_DIR"
    ls -lh "$CACHE_DIR"
else
    echo "Cache directory does not exist: $CACHE_DIR"
fi

# Check permissions
ls -ld "$CACHE_DIR"

# Check disk space
df -h "$CACHE_DIR"

Cache directory structure

The cache directory contains:

~/.cache/uv/
├── archive-v0/          # Extracted source distributions
├── built-wheels-v0/     # Wheels built from source
├── downloads-v0/        # Downloaded packages
├── git-v0/              # Git repository clones
└── simple-v0/           # Package index metadata

Configuration

Using environment variable

export UV_CACHE_DIR=/custom/cache/path
uv cache dir

Using command-line option

uv --cache-dir /custom/cache/path cache dir

Using configuration file

In uv.toml or pyproject.toml:

[tool.uv]
cache-dir = "/custom/cache/path"

Then:

uv cache dir

Temporary cache

uv --no-cache cache dir

This shows a temporary directory that will be discarded when uv exits.

Performance considerations

Same filesystem requirement

For optimal performance, the cache should be on the same filesystem as your Python environments:

# Check cache filesystem
df "$(uv cache dir)"

# Check project filesystem
df "$VIRTUAL_ENV"

# Should match for best performance

Why this matters:

• Same filesystem allows hardlinks (instant “copies”)
• Cross-filesystem requires actual file copies (slower)
• Clone mode (CoW) only works on same filesystem

Network filesystems

Avoid network filesystems for the cache:

# Bad: Network filesystem (slow)
export UV_CACHE_DIR=/mnt/nfs/uv-cache

# Good: Local filesystem (fast)
export UV_CACHE_DIR=~/.cache/uv

Platform-specific locations

Linux

uv cache dir
# /home/username/.cache/uv

# Or with XDG_CACHE_HOME
export XDG_CACHE_HOME=/custom/cache
uv cache dir
# /custom/cache/uv

macOS

uv cache dir
# /Users/username/.cache/uv

# Or Library/Caches (less common)
export XDG_CACHE_HOME=~/Library/Caches
uv cache dir
# /Users/username/Library/Caches/uv

Windows

uv cache dir
# C:\Users\Username\AppData\Local\uv\cache

# Or custom location
$env:UV_CACHE_DIR = "D:\CustomCache\uv"
uv cache dir
# D:\CustomCache\uv

Related commands

• uv cache clean - Remove cache entries
• uv cache prune - Remove unreachable cache entries
• uv cache size - Show cache size

Notes

• The cache directory is created automatically when first needed
• Cache location can be customized via environment variable or configuration
• For best performance, keep the cache on the same filesystem as your projects
• The cache is global and shared across all projects
• Network filesystems can significantly slow down uv operations
• The cache directory structure is versioned (e.g., archive-v0) for future compatibility