Cache - Bun

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/
├── 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:

Bun checks if the package exists in cache
If found, uses cached version (no download)
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

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:

Check network connectivity
Verify cache isn’t disabled
Check disk I/O performance
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

Commands

Configuration

Documentation Index

​Cache directory

​Custom cache directory

​Via bunfig.toml

​Via CLI flag

​Via environment variable

​Cache behavior

​What gets cached

​Cache structure

​Cache hits

​Disabling cache

​Disable completely

​Via bunfig.toml

​Via CLI flag

​Bypass cache temporarily

​Manifest cache

​Manifest cache directory

​Disable manifest cache

​Via bunfig.toml

​Via CLI flag

​Managing cache

​View cache size

​Clear cache

​View cache location

​Configuration

​bunfig.toml options

​Advanced cache settings

​CI/CD caching

​GitHub Actions

​GitLab CI

​Docker

​Cache invalidation

​Manual invalidation

​Cache sharing

​Multiple projects

​Multiple users

​Troubleshooting

​Cache corruption

​Out of disk space

​Permission errors

​Slow installs despite cache

​Performance tips

​Use cache on fast storage

​Periodic cache cleanup

​Cache in Docker

​Examples

​Disable cache temporarily

​Custom cache per project

​Shared team cache

Build docs developers (and LLMs) love

Cache directory

Custom cache directory

Via bunfig.toml

Via CLI flag

Via environment variable

Cache behavior

What gets cached

Cache structure

Cache hits

Disabling cache

Disable completely

Via bunfig.toml

Via CLI flag

Bypass cache temporarily

Manifest cache

Manifest cache directory

Disable manifest cache

Via bunfig.toml

Via CLI flag

Managing cache

View cache size

Clear cache

View cache location

Configuration

bunfig.toml options

Advanced cache settings

CI/CD caching

GitHub Actions

GitLab CI

Docker

Cache invalidation

Manual invalidation

Cache sharing

Multiple projects

Multiple users

Troubleshooting

Cache corruption

Out of disk space

Permission errors

Slow installs despite cache

Performance tips

Use cache on fast storage

Periodic cache cleanup

Cache in Docker

Examples

Disable cache temporarily

Custom cache per project

Shared team cache