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:
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.
This is the recommended flag for CI/CD pipelines. bun ci is a convenient alias:
Configure it permanently in bunfig.toml:
Generating a lockfile without installing
To resolve dependencies and write bun.lock without touching node_modules:
--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):
