What is the bun.lockb file?

The bun.lockb file ensures consistent dependencies across all environments in a Bun project. Imagine we’re working on a team project, and our project depends on several external libraries. Each of these packages also have their own dependencies. We’re not working on this project alone; our team members, including other developers on different machines, are collaborating with us. Without a lockfile, we might install version 1.0 of a package, while another developer installs version 2.0, leading to inconsistencies and perhaps groundbreaking changes in the project. That’s where lockfiles come in.

Imagine we're working on a team project, and our project depends on several external libraries. Each of these packages also have their own dependencies. We're not working on this project alone; our team members, including other developers on different machines, are collaborating with us. Without a lockfile, we might install version 1.0 of a package, while another developer installs version 2.0, leading to inconsistencies and perhaps groundbreaking changes in the project. That's where lockfiles come in.

Lockfiles serve as a guarantee that a project's dependencies remain uniform in various settings and over the course of time. They keep a record of the following:

  • The specific versions of all installed dependencies, encompassing both their subordinate dependencies and respective versions

  • The metadata associated with the packages

  • The installation sequence, and dependencies associated with each package

  • The resolved versions of those dependencies, an integrity hash (if present), and the specific resolution for each package

  • The corresponding version or its equivalent

Now, the pressing question is how these lockfiles come into existence. The process is quite straightforward, following the same method we've been using to generate lockfiles in Node.js – by executing an installation command.

Exploring the bun.lockb file

The bun.lockb file is created when we run the bun install command, and it's in a binary format. This format makes it faster to read and parse than lockfiles using JSON or YAML. Why is it faster, you ask? Well, it uses linear arrays to store all the data. Instead of package names, it refers to them using either an auto-incrementing number or a hash of the package name. For longer strings, those that are over 88 characters, it removes duplicates to save space. Before it's saved on our disk, the lockfile is optimized by cleaning up unnecessary data and arranged in a predictable order by following the package dependencies. This makes it much faster and more efficient.

In order to address platform-specific dependencies, Bun includes normalized CPU and OS values in the lockfile, in addition to the resolved packages. It omits downloading, extracting, and installing packages that are disabled for the current target during runtime. This ensures that the lockfile remains consistent across different platforms and architectures, even if the actual installed packages may vary.

A readable bun.lockb file

By default, the bun.lockb file is not readable as it’s a bunch of compiled code that only the machine can understand. However, if needed, we can actually generate a file that can be read by us. All we need to do is to use the --yarn flag to generate a Yarn-compatible yarn.lock file (in addition to bun.lockb) as shown below.

bun install --yarn

Let’s proceed to compare the two. We have a straightforward Remix project displayed in the terminal below, but we haven’t executed the bun install command yet. Please go ahead and run the command shown above, and then use the cat bun.lockb and cat yarn.lock commands to examine the resulting lockfiles.

Terminal 1
Terminal
Loading...

As we can see, this is a great tool to have in hand if we need to see what our lockfile looks like.

Not using lockfiles

Ideally, it’s advisable to use lockfiles. However, if you’re in an experimental phase and wish to explore alternative options, you can disable lockfile generation by using the following command:

bun install --no-save

Please proceed to run the bun install command once more, but this time with the —-no-save flag, and then attempt to execute cat bun.lockb. You’ll observe an error indicating that the lockfile does not exist.

Terminal 1
Terminal
Loading...

Conclusion

The bun.lockb file ensures consistency and reliability of a project’s dependencies. By documenting specific versions, dependencies, and platform-specific information, it guarantees uniformity across various settings and platforms.

Free Resources

Copyright ©2025 Educative, Inc. All rights reserved