Lockfile - Bun

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:
  [email protected]:
    resolved: https://registry.npmjs.org/react/-/react-18.2.0.tgz
    integrity: sha512-...
    dependencies:
      loose-envify: 1.4.0
  
  [email protected]:
    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|[email protected]|[email protected]|[email protected]

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:

Ensure same Bun version:

bun --version

Use same registry:

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

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/

Commands

Configuration

​Lockfile formats

​Binary lockfile (bun.lockb)

​Text lockfile (bun.lock)

​Choosing a format

​Binary lockfile (default)

​Text lockfile

​Configuration

​Use text lockfile

​Via bunfig.toml

​Via CLI flag

​Convert formats

​Lockfile behavior

​Automatic generation

​Lockfile updates

​Frozen lockfile

​Via bunfig.toml

​No lockfile

​Lockfile structure

​Binary lockfile

​Text lockfile format

​Lockfile commands

​View lockfile hash

​View hash string

​Print stored hash

​Migration

​From other package managers

​Version control

​Commit lockfile

​Ignore lockfile (not recommended)

​CI/CD

​GitHub Actions

​GitLab CI

​Troubleshooting

​Lockfile out of sync

​Merge conflicts

​Corrupted lockfile

​Different machines

​Custom lockfile path

​Set lockfile path

​Save lockfile to different location

​Workspaces

​Performance

​Binary lockfile

​Text lockfile

​Best practices

​Always commit lockfile

​Use frozen lockfile in CI

​Review lockfile changes

​Regenerate periodically

​Use text lockfile for open source

​Examples

​Enable text lockfile

​Switch to binary lockfile

​Frozen lockfile

​Migrate from npm

Build docs developers (and LLMs) love

Lockfile formats

Binary lockfile (bun.lockb)

Text lockfile (bun.lock)

Choosing a format

Binary lockfile (default)

Text lockfile

Configuration

Use text lockfile

Via bunfig.toml

Via CLI flag

Convert formats

Lockfile behavior

Automatic generation

Lockfile updates

Frozen lockfile

Via bunfig.toml

No lockfile

Lockfile structure

Binary lockfile

Text lockfile format

Lockfile commands

View lockfile hash

View hash string

Print stored hash

Migration

From other package managers

Version control

Commit lockfile

Ignore lockfile (not recommended)

CI/CD

GitHub Actions

GitLab CI

Troubleshooting

Lockfile out of sync

Merge conflicts

Corrupted lockfile

Different machines

Custom lockfile path

Set lockfile path

Save lockfile to different location

Workspaces

Performance

Binary lockfile

Text lockfile

Best practices

Always commit lockfile

Use frozen lockfile in CI

Review lockfile changes

Regenerate periodically

Use text lockfile for open source

Examples

Enable text lockfile

Switch to binary lockfile

Frozen lockfile

Migrate from npm