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

[install]
cache = "/custom/cache/path"

Via CLI flag

bun install --cache-dir /custom/cache/path

Via environment variable

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/
├── [e-mail]
├── [e-mail]
├── [e-mail]
└── ...

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

[install]
cache = false

Via CLI flag

bun install --no-cache

Bypass cache temporarily

Force re-download packages:

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

[install]
disableManifestCache = true

Via CLI flag

bun install --no-manifest-cache

Managing cache

View cache size

du -sh ~/.bun/install/cache

Example output:

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

Clear cache

bun pm cache rm

Output:

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

Or manually:

rm -rf ~/.bun/install/cache

View cache location

bun pm cache

Output:

/home/user/.bun/install/cache

Configuration

bunfig.toml options

[install]
# Disable cache entirely
cache = false

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

# Disable manifest cache
disableManifestCache = true

Advanced cache settings

[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:

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

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:

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:

# Clear cache
bun pm cache rm

# Reinstall
bun install

Or:

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

export BUN_INSTALL_CACHE_DIR=/shared/cache

Troubleshooting

Cache corruption

If you suspect cache corruption:

# Clear cache
bun pm cache rm

# Reinstall
rm -rf node_modules
bun install

Out of disk space

If cache is too large:

# Check size
du -sh ~/.bun/install/cache

# Clear cache
bun pm cache rm

Permission errors

If you get permission errors:

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

bun pm cache rm
bun install

Performance tips

Use cache on fast storage

For best performance, place cache on SSD:

[install]
cache = "/mnt/fast-ssd/bun-cache"

Periodic cache cleanup

Clean cache periodically to save disk space:

# Cron job to clear cache weekly
0 0 * * 0 bun pm cache rm

Cache in Docker

Use BuildKit cache mounts for fast Docker builds:

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

This caches packages across Docker builds.

Examples

Disable cache temporarily

# One-time install without cache
bun install --no-cache

# Normal install resumes using cache
bun install

Custom cache per project

# Use project-local cache
bun install --cache-dir ./.bun-cache

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

Shared team cache

# Set up shared cache directory
export BUN_INSTALL_CACHE_DIR=/mnt/shared/bun-cache

# All team members use same cache
bun install