bun.lock and bun.lockb: The Bun Lockfile
Bun pins the resolved dependency tree in a lockfile: the text bun.lock (current default) or the legacy binary bun.lockb.
The lockfile is what makes installs reproducible. Newer Bun writes a human-readable, diffable bun.lock; older projects may still carry the binary bun.lockb, which Bun can migrate.
What it does
The lockfile records the exact resolved version and integrity of every dependency so installs are deterministic. bun.lock is a JSONC text format that diffs cleanly in PRs. bun.lockb is the older binary format. Bun reads both and, on install, can migrate bun.lockb to bun.lock.
Common usage
bun install # writes/updates bun.lock
# migrate an old binary lockfile to text
bun install --save-text-lockfile
# inspect a binary lockfile as text
bun bun.lockb # prints a readable viewOptions
| Item | What it does |
|---|---|
| bun.lock | Text (JSONC) lockfile, the current default; commit it |
| bun.lockb | Legacy binary lockfile; still read, can be migrated |
| --save-text-lockfile | Force writing the text bun.lock format |
| bun bun.lockb | Print a binary lockfile in readable form |
In CI
Commit the lockfile and key your dependency cache on its hash (bun pm hash). The text bun.lock makes lockfile diffs reviewable in PRs, so prefer migrating off bun.lockb. Whichever you use, the same file must be present for --frozen-lockfile to install reproducibly.
Common errors in CI
"error: No lockfile found" under a frozen install means the lockfile was not committed (check .gitignore). A noisy, unreviewable diff means the repo still uses binary bun.lockb; migrate with --save-text-lockfile. Merge conflicts in bun.lock are resolved by re-running bun install and committing the regenerated file.