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.
Bun’s lockfile locks package versions for reproducible installs.
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
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
# With existing bun.lockb
bun install --save-text-lockfile
# Delete text lockfile
rm bun.lock
# Install to create binary lockfile
bun install
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
package.json.
Via bunfig.toml
[install]
frozenLockfile = true
No lockfile
Install without creating/updating lockfile:
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
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:
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
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
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
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
# 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:
- Use same registry:
# bunfig.toml
[install]
registry = "https://registry.npmjs.org/"
- Regenerate lockfile:
Custom lockfile path
Set lockfile path
[install.lockfile]
path = "custom.lockb"
[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
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:
Check for:
- Unexpected version changes
- New dependencies
- Removed dependencies
Regenerate periodically
Regenerate lockfile to clean up:
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/
