Lockfile

Bun’s lockfile locks package versions for reproducible installs.

Lockfile formats

Bun supports two lockfile formats:

Binary lockfile (bun.lockb)

Default format. Fast to read/write, compact size.

$ ls -lh bun.lockb
-rw-r--r-- 1 user user 147K Dec 1 10:00 bun.lockb

Text lockfile (bun.lock)

Human-readable format, better for version control diffs.

$ ls -lh bun.lock  
-rw-r--r-- 1 user user 456K Dec 1 10:00 bun.lock

Choosing a format

Binary lockfile (default)

Best for:

• Large projects with many dependencies
• Faster CI/CD pipelines
• Private projects with less merge conflicts

Advantages:

• 3x faster to parse
• 3x smaller file size
• Less disk I/O

Disadvantages:

• Not human-readable
• Binary diffs in version control

Text lockfile

Best for:

• Open source projects
• Projects requiring human review of dependency changes
• Better git diffs

Advantages:

• Human-readable
• Reviewable diffs
• Easy to debug

Disadvantages:

• Larger file size
• Slower parsing

Configuration

Use text lockfile

Via bunfig.toml

[install]
saveTextLockfile = true

Via CLI flag

Generate text lockfile on next install:

bun install --save-text-lockfile

Convert formats

Convert binary to text:

# With existing bun.lockb
bun install --save-text-lockfile

Convert text to binary:

# Delete text lockfile
rm bun.lock

# Install to create binary lockfile
bun install

Or configure in bunfig.toml:

[install]
saveTextLockfile = false

Lockfile behavior

Automatic generation

Bun automatically creates/updates the lockfile:

$ bun install
$ ls
bun.lockb  package.json  node_modules/

Lockfile updates

The lockfile updates when:

• Installing new packages
• Removing packages
• Updating package versions
• Changing version ranges in package.json

Frozen lockfile

Prevent lockfile updates (useful in CI):

bun install --frozen-lockfile

Fails if lockfile is out of sync with package.json.

Via bunfig.toml

[install]
frozenLockfile = true

No lockfile

Install without creating/updating lockfile:

bun install --no-save

Lockfile structure

Binary lockfile

Binary format (not human-readable):

$ file bun.lockb
bun.lockb: data

Text lockfile format

# bun.lock
name: my-app
version: 1.0.0

packages:
  react@18.2.0:
    resolved: https://registry.npmjs.org/react/-/react-18.2.0.tgz
    integrity: sha512-...
    dependencies:
      loose-envify: 1.4.0
  
  typescript@5.0.0:
    resolved: https://registry.npmjs.org/typescript/-/typescript-5.0.0.tgz
    integrity: sha512-...

Lockfile commands

View lockfile hash

$ bun pm hash
f3d8b2a1c4e5d6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

The hash represents the lockfile state.

View hash string

$ bun pm hash-string
packages|react@18.2.0|react-dom@18.2.0|typescript@5.0.0

Print stored hash

$ bun pm hash-print
f3d8b2a1c4e5d6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Migration

From other package managers

Migrate existing lockfiles:

bun pm migrate

Supported lockfiles:

• package-lock.json (npm)
• yarn.lock (Yarn)
• pnpm-lock.yaml (pnpm)

Example:

$ bun pm migrate
Migrated from package-lock.json to bun.lock

Force migration (overwrite existing):

bun pm migrate --force

Version control

Commit lockfile

Always commit your lockfile:

git add bun.lockb  # or bun.lock
git commit -m "Lock dependencies"

Ignore lockfile (not recommended)

If you must ignore lockfile:

# .gitignore
bun.lockb
bun.lock

Warning: This makes installs non-reproducible.

CI/CD

GitHub Actions

Cache and use lockfile:

name: CI
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
      
      - name: Install dependencies
        run: bun install --frozen-lockfile
      
      - name: Run tests
        run: bun test

GitLab CI

image: oven/bun:latest

before_script:
  - bun install --frozen-lockfile

test:
  script:
    - bun test

Troubleshooting

Lockfile out of sync

If lockfile doesn’t match package.json:

$ bun install --frozen-lockfile
error: lockfile out of sync with package.json

Fix:

bun install
git add bun.lockb
git commit -m "Update lockfile"

Merge conflicts

For binary lockfile conflicts:

# Use their version
git checkout --theirs bun.lockb
bun install

# Or use our version
git checkout --ours bun.lockb  
bun install

# Or regenerate
rm bun.lockb
bun install

For text lockfile conflicts:

# Resolve in editor
vim bun.lock

# Or regenerate
rm bun.lock
bun install

Corrupted lockfile

If lockfile is corrupted:

rm bun.lockb  # or bun.lock
bun install

Different machines

If lockfile differs between machines:

1. Ensure same Bun version:

bun --version

2. Use same registry:

# bunfig.toml
[install]
registry = "https://registry.npmjs.org/"

3. Regenerate lockfile:

rm bun.lockb
bun install

Custom lockfile path

Set lockfile path

[install.lockfile]
path = "custom.lockb"

Or:

[install.lockfile]  
path = "locks/dependencies.lock"

Save lockfile to different location

[install.lockfile]
savePath = "locks/bun.lock"

Workspaces

In workspace projects, use a single root lockfile:

my-monorepo/
├── package.json
├── bun.lockb          # Shared lockfile
├── packages/
│   ├── app/
│   │   └── package.json
│   └── shared/
│       └── package.json

All workspace dependencies are tracked in the root lockfile.

Performance

Binary lockfile

• Read time: ~5-10ms for 1000 packages
• Write time: ~10-20ms for 1000 packages
• File size: ~100-200KB for 1000 packages

Text lockfile

• Read time: ~15-30ms for 1000 packages
• Write time: ~30-60ms for 1000 packages
• File size: ~300-600KB for 1000 packages

Best practices

Always commit lockfile

git add bun.lockb
git commit -m "Update dependencies"

Use frozen lockfile in CI

run: bun install --frozen-lockfile

Review lockfile changes

For text lockfiles:

git diff bun.lock

Check for:

• Unexpected version changes
• New dependencies
• Removed dependencies

Regenerate periodically

Regenerate lockfile to clean up:

rm bun.lockb
bun install

Use text lockfile for open source

Easier for contributors to review:

[install]
saveTextLockfile = true

Examples

Enable text lockfile

# bunfig.toml
[install]
saveTextLockfile = true

bun install
ls
# bun.lock  package.json  node_modules/

Switch to binary lockfile

# bunfig.toml
[install]
saveTextLockfile = false

rm bun.lock
bun install
ls
# bun.lockb  package.json  node_modules/

Frozen lockfile

$ bun install --frozen-lockfile
bun install v1.0.0

 134 packages installed [1.42s]

Migrate from npm

$ ls
package.json  package-lock.json  node_modules/

$ bun pm migrate
Migrated from package-lock.json to bun.lock

$ ls
package.json  bun.lock  node_modules/