Running bun install creates a lockfile called bun.lock in the project root. The lockfile records the exact resolved version of every dependency in the tree, ensuring that installs are reproducible across machines and over time.
Should I commit bun.lock?
Yes. Committing bun.lock to version control ensures that everyone on your team and your CI environment installs the exact same package versions.
Bun v1.2 introduced a text-based lockfile (bun.lock). Prior to v1.2, the lockfile was a binary file named bun.lockb.
The text-based format has several advantages:
- Human-readable: you can inspect and review changes in pull requests
- Diffable: standard
git diff works on bun.lock
- Mergeable: conflicts can be resolved manually
To migrate an existing bun.lockb to the new text format:
bun install --save-text-lockfile --frozen-lockfile --lockfile-only
rm bun.lockb
Frozen lockfile
Use --frozen-lockfile to install exact versions from bun.lock without modifying it. The install will fail if package.json and bun.lock are out of sync.
bun install --frozen-lockfile
bun ci is a convenient alias:
Configure it permanently in bunfig.toml:
[install]
frozenLockfile = true
Generating a lockfile without installing
To resolve dependencies and write bun.lock without touching node_modules:
bun install --lockfile-only
--lockfile-only still populates the global install cache with registry metadata and any git or tarball dependencies.
Skipping the lockfile
To install without creating or updating the lockfile:
Generating a Yarn-compatible lockfile
To write a Yarn v1-style yarn.lock alongside bun.lock:
Automatic lockfile migration
When bun install runs in a project without a bun.lock, Bun automatically migrates from existing lockfiles:
yarn.lock (Yarn v1)package-lock.json (npm)pnpm-lock.yaml (pnpm v7+)
The original lockfile is preserved. You can remove it manually after verifying the migration.
Lockfile hash
To inspect the lockfile hash (useful for caching in CI):
bun pm hash # generate and print the hash
bun pm hash-print # print the hash stored in bun.lock
bun pm hash-string # print the string used to compute the hash
