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.

When a project has lockfiles of several package managers, Bun migrates the first one it can, in this order: npm-shrinkwrap.json, package-lock.json, yarn.lock, pnpm-lock.yaml. It prints a warning for each one it had to skip.

Bun does not migrate an npm lockfile from npm 6 or older (lockfileVersion 1); it prints a warning and, when there is no other lockfile, 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.