Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us