Lockfile

bun install creates a lockfile called bun.lock.

Should it be committed to git?#

Yes

Generate a lockfile without installing?#

To generate a lockfile without installing to node_modules, use the --lockfile-only flag. Bun always saves the lockfile to disk, even if it is already up to date with your project's package.json(s). The exceptions are --frozen-lockfile (or --production), --dry-run, and --no-save, which save nothing.

bun install --lockfile-only

bun add, bun remove, and bun update also accept --lockfile-only.

Can I opt out?#

To install without creating a lockfile:

bun install --no-save

To write a Yarn lockfile in addition to bun.lock:

bun install --yarn

[install.lockfile]
# whether to save a non-Bun lockfile alongside bun.lock
# only "yarn" is supported
print = "yarn"

Text-based lockfile#

Bun v1.2 changed the default lockfile format to the text-based bun.lock. To migrate an existing binary bun.lockb, run bun install --save-text-lockfile --frozen-lockfile --lockfile-only and delete bun.lockb.

For more on the format, see the blog post.

Automatic lockfile migration#

When you run bun install in a project without a bun.lock, Bun automatically migrates existing lockfiles:

• yarn.lock (Yarn v1, and Yarn 2+ "Berry")
• npm-shrinkwrap.json and package-lock.json (npm, lockfileVersion 2, 3 or 4)
• pnpm-lock.yaml (pnpm)

When a project has both npm lockfiles, Bun reads npm-shrinkwrap.json and ignores package-lock.json, as npm does.

Bun does not migrate an npm lockfile from npm 6 or older (lockfileVersion 1); it prints a warning and resolves from package.json instead.

Bun preserves the original lockfile. You can remove it manually after verification.

Bun writes the migrated bun.lock only when the command saves a lockfile. bun install --frozen-lockfile (and bun ci), --dry-run, --no-save, and read-only commands such as bun outdated use the migrated lockfile in memory and write nothing. Under --frozen-lockfile, Bun prints a note: asking you to run bun install and commit the result. To migrate without installing, run bun pm migrate or bun install --lockfile-only.