Upgrade your Development Environments with Devbox

Development Environment Rot

Have you ever had the experience of stepping back into an old project and nothing works anymore? You can’t build, deploy, or do anything with it, even though everything worked the last time you were working on it. Development environments that use your system’s software will eventually rot because of software drift. For example, you might install a newer version of node that is no longer backwards-compatible with the code in your project, or you might not have installed sharp when you setup your new laptop and your project depends on it.

A Devbox project will work a decade from now just as well as it does today.

Project Isolation

If you’re working on five separate projects there’s no reason they all need to use the same global version of every piece of software. Maybe one project uses Ruby 2 and another project uses Ruby 3. Should you have to upgrade all your projects in one go? Do you communicate to your collaborators that they need to update their systems and all their projects in one go? Is that even feasible?

Devbox allows your projects to co-exist while using different versions of software.

Keeping Things Native and Local

There are many solutions to having isolated, reproducible development environments. Two more popular solutions are remote developer boxes (usually powered by containers or VMs) and Docker Desktop.

There are many downsides to having your development environment in a VM (which is what Docker Desktop uses on macOS and Windows), such as deciding how much memory to allocate to the VM, the performance hit of using a VM, the disconnect of having to mount your project files in the VM, the battery life (or even just power efficiency) hit of running a VM, etc.

Remote development has so many headaches I’m not going to enumerate them.

Devbox makes it so that you are running local, native software, you’re using your regular file system, etc. There are no VMs or containers to get in the way and your mental model for where and how software is running can be extremely simple.

Share Your Development Environment with Your Collaborators

Does your team maintain a wiki where you keep instructions on how to setup a development environment? Is it always out of date?

Does your open source project give instructions on how to setup the software required to build and run your project?

With Devbox, if you test a new version of a package and it works, all you have to do is commit the changes to devbox.json and devbox.lock to your project. If you push those changes to a shared repository, your collaborators that pull those files will start using the new version of the package you tested, without any discussion required. Everyone will stay in sync, automatically.

What’s Going on under the Covers?

Highly optional section: feel free to skip!

Adding packages to your Devbox project modifies two files:

1. devbox.json - a human readable/editable manifest of what packages and configuration you have for the Devbox shell in that directory:

   devbox.json

   1{
   2  "packages": ["hello@latest"],
   3  /* ... */
   4}
   

   devbox.json

   1{
   2  "packages": ["hello@latest"],
   3  /* ... */
   4}
   

2. devbox.lock - this is analogous to something like a package-lock.json file, where the exact version of the software you requested is stored away to be re-used later. This makes it so that even if you install a package with something like devbox add nodejs@latest, the exact version will be stored in devbox.lock and re-used later anytime you enter the Devbox shell, so you will still always get the same version.

   devbox.lock

   1{
   2  "lockfile_version": "1",
   3  "packages": {
   4    "hello@latest": {
   5      "last_modified": "2023-10-25T20:49:13Z",
   6      "resolved": "github:NixOS/nixpkgs/75a52265bda7fd25e06e3a67dee3f0354e73243c#hello",
   7      "source": "devbox-search",
   8      "version": "2.12.1"
   9      /* ... */
   10    }
   11  }
   12}
   

   devbox.lock

   1{
   2  "lockfile_version": "1",
   3  "packages": {
   4    "hello@latest": {
   5      "last_modified": "2023-10-25T20:49:13Z",
   6      "resolved": "github:NixOS/nixpkgs/75a52265bda7fd25e06e3a67dee3f0354e73243c#hello",
   7      "source": "devbox-search",
   8      "version": "2.12.1"
   9      /* ... */
   10    }
   11  }
   12}
   

   The packages array in devbox.json maps to the same packages key in devbox.lock, in this case hello@latest. In the devbox.lock file it stores what precise package that resolved to, in this case: github:NixOS/nixpkgs/75a52265bda7fd25e06e3a67dee3f0354e73243c#hello". That maps to a precise version of hello that you can find right on GitHub.

When you run devbox shell, Devbox will check your devbox.json, observe that you want hello@latest, find that in devbox.lock, lookup the exact version, download and build the package as necessary, and make it available in your shell. You can see the version of hello will match the version in your devbox.lock:

1(devbox) ➜  hello --version
2hello (GNU Hello) 2.12.1

1(devbox) ➜  hello --version
2hello (GNU Hello) 2.12.1

Both of these files should be committed to version control.

And if you want to find out where the package lives:

1➜ devbox shell
2Ensuring packages are installed.
3Starting a devbox shell...
4(devbox) ➜ which hello
5/Users/alan/src/devbox-article-sandbox/.devbox/nix/profile/default/bin/hello

1➜ devbox shell
2Ensuring packages are installed.
3Starting a devbox shell...
4(devbox) ➜ which hello
5/Users/alan/src/devbox-article-sandbox/.devbox/nix/profile/default/bin/hello

Which is a hard-link into the Nix store:

/nix/store/2nsd0qwv17v6shhhmknyrpscjsa0p78r-hello-2.12.1/bin/hello

Wait, What is Nix?

Nix is a programming language (nixlang), an operating system (NixOS), and a package manager (nixpkg)².

The package manager is the largest in the world and, under the covers, powers all the software you are using with Devbox. Devbox exists to hide the complexity of Nix while exposing a small but very powerful set of ideas that are super useful.

Nix is there under the covers, but you don’t need to know anything about it at all. Devbox is not a leaky abstraction: you can use Devbox and never think about or understand a single aspect of Nix, ever.

Browser Playground

Want to just mess around without committing to anything? The Devbox team has created a great browser-based playground for playing with Devbox which you can jump into here.

Installation and Initialization

Install on your machine with:

1curl -fsSL https://get.jetpack.io/devbox | bash

1curl -fsSL https://get.jetpack.io/devbox | bash

Initialize Devbox in an existing project:

1cd ~/src/myproject # or use a new "devbox-testing" directory to experiment
2devbox init # creates starter devbox.json and devbox.lock files

1cd ~/src/myproject # or use a new "devbox-testing" directory to experiment
2devbox init # creates starter devbox.json and devbox.lock files

Test that everything works:

1devbox shell # Start your devbox shell to make "hello" available
2devbox add hello # Add the "hello" test package
3hello # test that the command runs, outputs "Hello, world!"
4exit # exit the devbox shell
5hello # should produce a "command not found" error

1devbox shell # Start your devbox shell to make "hello" available
2devbox add hello # Add the "hello" test package
3hello # test that the command runs, outputs "Hello, world!"
4exit # exit the devbox shell
5hello # should produce a "command not found" error

If you’re in a repository, commit the Devbox artifacts to version control:

1git add devbox.json devbox.lock
2git commit -m "Adding Devbox developer environment"

1git add devbox.json devbox.lock
2git commit -m "Adding Devbox developer environment"

Searching for and Installing Packages

There are two ways to search for packages with Devbox. One is directly from the CLI:

1(devbox) ➜ devbox search node
2Found 7+ results for "node":
3
4* nodejs  (21.1.0, 21.0.0, 20.9.0, 20.8.0, 20.7.0, 20.6.1, 20.5.1, 20.5.0, 20.4.0, 20.3.1)
5* nodenv  (1.4.1, 1.4.0)
6* nodehun  (3.0.2)
7* node2nix  (1.11.0, 1.10.0)
8* node-glob  (10.3.3)
9* node-manta  (5.4.1, 5.3.2)
10* nodejs-slim  (21.1.0, 21.0.0, 20.9.0, 20.8.0, 20.7.0, 20.6.1, 20.5.1, 20.5.0, 20.4.0, 20.3.1)
11
12Warning: Showing top 10 results and truncated versions. Use --show-all to show all.
13

1(devbox) ➜ devbox search node
2Found 7+ results for "node":
3
4* nodejs  (21.1.0, 21.0.0, 20.9.0, 20.8.0, 20.7.0, 20.6.1, 20.5.1, 20.5.0, 20.4.0, 20.3.1)
5* nodenv  (1.4.1, 1.4.0)
6* nodehun  (3.0.2)
7* node2nix  (1.11.0, 1.10.0)
8* node-glob  (10.3.3)
9* node-manta  (5.4.1, 5.3.2)
10* nodejs-slim  (21.1.0, 21.0.0, 20.9.0, 20.8.0, 20.7.0, 20.6.1, 20.5.1, 20.5.0, 20.4.0, 20.3.1)
11
12Warning: Showing top 10 results and truncated versions. Use --show-all to show all.
13

The other is on the web. The Devbox team put together https://www.nixhub.io which makes searching for Nix packages as a Devbox user a little more intuitive³.

Workflow Tips

1# ⚠️ okay
2devbox add git

1# ⚠️ okay
2devbox add git

1# ✅ better
2devbox search git
3devbox add git@2.42.0

1# ✅ better
2devbox search git
3devbox add git@2.42.0

Comparison to Homebrew/Chocolatey

• ✅ With Devbox, per-project package isolation is easy. With Homebrew, everything is global.
• ❌ Sometimes you just want a package, and you want it everywhere. For example: are you using a tool you didn’t start from a Devbox shell, and it expects git to be available. It won’t find it. Devbox doesn’t excel at this.
• ✅ Devbox, by virtue of using Nix, has more packages then any other package manager.
• ✅ Devbox developer environments are more reproducible. Even the modified date of the package binary will be the same on your system and your collaborators!
• ❌ I’ve seen new package versions be available in Homebrew more quickly than Devbox (e.g. bun.sh). That’s not common and major packages like Node.js are available very quickly with Devbox, so this has never been an issue for me, but it’s something you can check on if it’s important to you.

Comparison to Docker

I’ve never liked the circuitousness of using Docker Desktop for my dev environment. It solves a lot of problems well but it seems like Devbox solves those problems much better, without having a layer of indirection through a virtual machine. I want to just cd into my project directory without having to bind mount my code into the container. I don’t want to have to even think about that layer of indirection.

Which is all to say I’m not even going to really compare the two.

Comparison to Devenv

devenv solves the same problem as Devbox: creating per-project, isolated development environments. The biggest difference is that Devbox totally abstracts Nix away from you while devenv is a leakier (and therefore more powerful) abstraction that lets you use more of Nix by requiring that you use Nix (and know how to use Nix). Instead of a very simple array of package names as strings, you write a devenv.nix file using the Nix language.

The Devbox founder said it well:

“Devbox is trying to give you the power of nix, but with a simplified interface that matches the simplicity of a package manager like yarn. If you want reproducible environments by simply specifying the list of packages you depend on, and not having to learn a new language, then Devbox is a great match.”

Note that you can install packages from Nix flakes with Devbox, which gets you a ton of that power, but it’s more of a side feature than part of the core of how it works. I’ve used a custom flake with Devbox exactly once, when I need to install the Mercurial package with the hg-evolve extension (which isn’t available by default).

Oh, and Devbox just gives you package semver so you don’t have to think about Nix package names and how that maps to versions. If I want nodejs@20.9.0 I don’t want to think about which Nix package has that version of Node.js, which is another benefit over devenv.

Comparison to Nix

If you’re capable of using Nix to manage all the packages on your system, all shall love you and despair.