> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache

Bun's cache system stores downloaded packages to speed up installations.

## Cache directory

By default, Bun stores cached packages in:

* **macOS/Linux**: `~/.bun/install/cache`
* **Windows**: `%USERPROFILE%\.bun\install\cache`

### Custom cache directory

Set a custom cache directory:

#### Via bunfig.toml

```toml theme={null}
[install]
cache = "/custom/cache/path"
```

#### Via CLI flag

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

#### Via environment variable

```bash theme={null}
export BUN_INSTALL_CACHE_DIR=/custom/cache/path
bun install
```

## Cache behavior

### What gets cached

Bun caches:

* **Tarballs** - Downloaded package tarballs from registries
* **Extracted packages** - Unpacked package contents
* **Git repositories** - Cloned git dependencies
* **Package metadata** - Registry responses (manifests)

### Cache structure

```
~/.bun/install/cache/
├── react@18.2.0.tgz
├── react-dom@18.2.0.tgz
├── typescript@5.0.0.tgz
└── ...
```

Packages are stored by name and version.

### Cache hits

When installing a package:

1. Bun checks if the package exists in cache
2. If found, uses cached version (no download)
3. If not found, downloads and adds to cache

Typical cache hit install: **\< 100ms** per package

## Disabling cache

### Disable completely

#### Via bunfig.toml

```toml theme={null}
[install]
cache = false
```

#### Via CLI flag

```bash theme={null}
bun install --no-cache
```

### Bypass cache temporarily

Force re-download packages:

```bash theme={null}
bun install --force
```

This downloads packages even if they exist in cache.

## Manifest cache

Bun also caches package metadata (manifests) from registries.

### Manifest cache directory

* **macOS/Linux**: `~/.bun/install/cache/manifests`
* **Windows**: `%USERPROFILE%\.bun\install\cache\manifests`

### Disable manifest cache

#### Via bunfig.toml

```toml theme={null}
[install]
disableManifestCache = true
```

#### Via CLI flag

```bash theme={null}
bun install --no-manifest-cache
```

## Managing cache

### View cache size

```bash theme={null}
du -sh ~/.bun/install/cache
```

Example output:

```
2.4G	/home/user/.bun/install/cache
```

### Clear cache

```bash theme={null}
bun pm cache rm
```

Output:

```
Cleared 'bun install' cache
Cleared 12 cached 'bunx' packages
```

Or manually:

```bash theme={null}
rm -rf ~/.bun/install/cache
```

### View cache location

```bash theme={null}
bun pm cache
```

Output:

```
/home/user/.bun/install/cache
```

## Configuration

### bunfig.toml options

```toml theme={null}
[install]
# Disable cache entirely
cache = false

# Custom cache directory
cache = "/path/to/cache"

# Disable manifest cache
disableManifestCache = true
```

### Advanced cache settings

```toml theme={null}
[install.cache]
# Disable cache
disable = true

# Disable manifest cache
disableManifest = true

# Custom cache directory
dir = "/custom/cache/path"
```

## CI/CD caching

### GitHub Actions

Cache Bun packages between runs:

```yaml theme={null}
name: CI
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest
      
      # Cache Bun dependencies
      - uses: actions/cache@v3
        with:
          path: ~/.bun/install/cache
          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
          restore-keys: |
            ${{ runner.os }}-bun-
      
      - run: bun install
      - run: bun test
```

### GitLab CI

```yaml theme={null}
image: oven/bun:latest

cache:
  key:
    files:
      - bun.lockb
  paths:
    - .bun/install/cache

before_script:
  - export BUN_INSTALL_CACHE_DIR=.bun/install/cache
  - bun install

test:
  script:
    - bun test
```

### Docker

Cache Bun packages in Docker:

```dockerfile theme={null}
FROM oven/bun:latest

WORKDIR /app

# Copy lockfile
COPY bun.lockb .

# Mount cache during install
RUN --mount=type=cache,target=/root/.bun/install/cache \
    bun install --frozen-lockfile

COPY . .

CMD ["bun", "run", "start"]
```

## Cache invalidation

Bun invalidates cache when:

* Package version changes
* Package tarball checksum changes
* Registry URL changes
* Bun version changes (major updates)

### Manual invalidation

Force cache invalidation:

```bash theme={null}
# Clear cache
bun pm cache rm

# Reinstall
bun install
```

Or:

```bash theme={null}
# Force re-download
bun install --force
```

## Cache sharing

### Multiple projects

The cache is shared across all projects on your machine:

```
Project A: react@18.2.0
Project B: react@18.2.0  → Uses cached version (instant!)
```

### Multiple users

Each user has their own cache directory:

```
User A: ~/.bun/install/cache
User B: ~/.bun/install/cache
```

To share cache between users, use a custom cache directory:

```bash theme={null}
export BUN_INSTALL_CACHE_DIR=/shared/cache
```

## Troubleshooting

### Cache corruption

If you suspect cache corruption:

```bash theme={null}
# Clear cache
bun pm cache rm

# Reinstall
rm -rf node_modules
bun install
```

### Out of disk space

If cache is too large:

```bash theme={null}
# Check size
du -sh ~/.bun/install/cache

# Clear cache
bun pm cache rm
```

### Permission errors

If you get permission errors:

```bash theme={null}
# Fix permissions
chmod -R u+w ~/.bun/install/cache

# Or use a different cache directory
bun install --cache-dir ./local-cache
```

### Slow installs despite cache

If installs are slow even with cache:

1. Check network connectivity
2. Verify cache isn't disabled
3. Check disk I/O performance
4. Try clearing and rebuilding cache:

```bash theme={null}
bun pm cache rm
bun install
```

## Performance tips

### Use cache on fast storage

For best performance, place cache on SSD:

```toml theme={null}
[install]
cache = "/mnt/fast-ssd/bun-cache"
```

### Periodic cache cleanup

Clean cache periodically to save disk space:

```bash theme={null}
# Cron job to clear cache weekly
0 0 * * 0 bun pm cache rm
```

### Cache in Docker

Use BuildKit cache mounts for fast Docker builds:

```dockerfile theme={null}
RUN --mount=type=cache,target=/root/.bun/install/cache \
    bun install --frozen-lockfile
```

This caches packages across Docker builds.

## Examples

### Disable cache temporarily

```bash theme={null}
# One-time install without cache
bun install --no-cache

# Normal install resumes using cache
bun install
```

### Custom cache per project

```bash theme={null}
# Use project-local cache
bun install --cache-dir ./.bun-cache

# Add to .gitignore
echo ".bun-cache" >> .gitignore
```

### Shared team cache

```bash theme={null}
# Set up shared cache directory
export BUN_INSTALL_CACHE_DIR=/mnt/shared/bun-cache

# All team members use same cache
bun install
```