Lockfile

Bun’s lockfile ensures reproducible installs across machines and over time.

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.

Lockfile format

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

This is the recommended flag for CI/CD pipelines. bun ci is a convenient alias:

bun ci

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:

bun install --no-save

Generating a Yarn-compatible lockfile

To write a Yarn v1-style yarn.lock alongside bun.lock:

bun install --yarn

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