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

# uv cache dir

Show the cache directory.

## Usage

```bash theme={null}
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

```bash theme={null}
uv cache dir
```

Expected output (Unix/macOS):

```
/home/username/.cache/uv
```

Expected output (Windows):

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

### Use in scripts

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
cd "$(uv cache dir)"
ls -lh
```

### Backup cache directory

Create a backup of your cache:

```bash theme={null}
CACHE_DIR=$(uv cache dir)
tar -czf uv-cache-backup.tar.gz "$CACHE_DIR"
```

### Monitor cache size

Check cache disk usage:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```yaml theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
export UV_CACHE_DIR=/custom/cache/path
uv cache dir
```

### Using command-line option

```bash theme={null}
uv --cache-dir /custom/cache/path cache dir
```

### Using configuration file

In `uv.toml` or `pyproject.toml`:

```toml theme={null}
[tool.uv]
cache-dir = "/custom/cache/path"
```

Then:

```bash theme={null}
uv cache dir
```

### Temporary cache

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```powershell theme={null}
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`](/cli/cache-clean) - Remove cache entries
* [`uv cache prune`](/cli/cache-prune) - Remove unreachable cache entries
* [`uv cache size`](/cli/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