DEV Community

Cover image for Reproducible Dev Environments
Amin Khozaei
Amin Khozaei

Posted on

Reproducible Dev Environments

#devbox #development #nix #flake

Modern projects need consistent, repeatable environments across developer machines, CI, and production. Discrepancies between development, testing, and production environments can lead to countless hours of debugging, configuration drift, and frustrating deployment failures. The core challenge is ensuring that every developer, and every server, is working with the exact same set of tools, libraries, and dependencies.

This post explains the ideas behind Nix and Flakes first, then shows how Devbox lets you use those ideas day to day, without writing Nix expressions, and how direnv turns it into a seamless, per‑directory experience.

1. Nix

Nix represents a paradigm shift in package management by utilizing the principles of functional programming to achieve deterministic, reproducible software environments. Unlike traditional systems like apt that modify a global state, Nix manages packages in a purely functional way. This means builds are isolated, dependencies are version-controlled, and state does not interfere across installations. This approach enhances reliability and simplifies configuration management by allowing entire environments to be rolled back, rebuilt, or replicated with precision.

1.1. Core Concepts

Central to Nix’s philosophy is the concept of immutability. In computing, immutability refers to the inability to modify a data object after its creation. In the context of Nix, this means software packages and configurations are never altered once they are built. Each package is associated with a unique identifier, derived from applying a cryptographic hash function to its source code and all its dependencies. This approach ensures that identical builds always produce identical outputs, leading to perfect reproducibility across systems.

A key feature of the Nix package manager is its use of a store, typically located at /nix/store. This directory holds all installed packages. Packages are stored in paths determined by hashing their build instructions and dependencies, ensuring that identical configurations always yield identical paths. For example, a specific version of gcc might live at a path like /nix/store/s66j5b...-gcc-11.3.0/. This thorough approach prevents unplanned modifications or interferences, offering a robust foundation for any reproducible build system.

1.2. Installing Nix

The installation process for Nix varies slightly depending on your operating system. The recommended method is to use the official installer from the Nix Package Manager.

1.2.1. Linux

If you are on Linux running systemd, use Multi-user installation (with root permission):

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon
Enter fullscreen mode Exit fullscreen mode

Otherwise, use Single-user installation (with normal user):

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --no-daemon
Enter fullscreen mode Exit fullscreen mode

1.2.2. MacOS

On MacOS, the only available option is Multi-user, so:

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install)
Enter fullscreen mode Exit fullscreen mode

1.2.3. Windows

Implementation on Windows environments is markedly different. Windows users need to use the Windows Subsystem for Linux (WSL), which provides a Linux kernel interface within a Windows environment.

  • First, you are required to enable WSL through Windows PowerShell with administrative privileges: 
wsl --install
Enter fullscreen mode Exit fullscreen mode

  • Following the WSL installation, you must install a Linux distribution, such as Ubuntu, from the Microsoft Store.

  • Upon launching the installed Linux distribution, you can perform the Linux-based installation as described in section 1.2.1.

After installation, you may need to source the Nix script in your shell's configuration file (e.g., .zshrc, .bashrc) to make the nix command available in new terminal sessions.

1.3. Creating Isolated Environments with nix-shell

An essential feature of Nix is the ability to define temporary, isolated environments called Nix shells. This is done by creating a shell.nix file in your project directory. This file declaratively lists all the packages your project needs.

Let's create a simple shell.nix file that provides the hello utility:

# shell.nix
{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  # buildInputs is the list of packages you want in your environment.
  buildInputs = [ 
    pkgs.hello 
  ];

  # shellHook is a script that runs when you enter the shell.
  shellHook = ''
    export MY_VAR="Hello, Nix!"
  '';
}
Enter fullscreen mode Exit fullscreen mode

To activate this environment, navigate to the project directory and run:

nix-shell
Enter fullscreen mode Exit fullscreen mode

Your shell prompt will change, indicating you are now inside the Nix shell. Here, the hello command is available, and the MY_VAR environment variable is set.

[nix-shell:~/my-project]$ hello
Hello, world!

[nix-shell:~/my-project]$ echo $MY_VAR
Hello, Nix!
Enter fullscreen mode Exit fullscreen mode

When you exit the shell (exit), your original environment is restored, and hello is no longer in your PATH. This powerful feature ensures that project dependencies don't pollute your global system.

2. Nix Flakes

While nix-shell is powerful, it has some reproducibility issues. For instance, import {} points to a "channel" of packages on your system that can change over time, meaning your shell.nix file could produce different environments on different days or different machines.

Flakes are the modern solution to this problem. They are a new feature in Nix designed to improve reproducibility, composability, and usability. Flakes allow hermetic, reproducible evaluation of multi-repository Nix projects, impose a discoverable standard structure, and replace older mechanisms like Nix channels.

2.1. Anatomy of a Flake

A flake is simply a directory containing a flake.nix file. This file has a standardized structure with two main sections: inputs and outputs.

inputs: These are the dependencies of your flake. They can be other flakes, such as the official nixpkgs repository, and are pinned to a specific Git commit.
outputs: These are the things your flake provides, such as packages, development shells (devShells), or NixOS configurations.
All flake inputs are pinned to specific revisions in a lockfile called flake.lock. This file, which is automatically generated and updated, ensures that every evaluation of the flake uses the exact same versions of its dependencies, achieving true reproducibility.

If you've worked with JavaScript (package.json/package-lock.json), Go (go.mod/go.sum), or Rust (Cargo.toml/Cargo.lock), this concept will feel very familiar. flake.nix is like package.json, describing the project, and flake.lock is like package-lock.json, ensuring deterministic builds.

2.2. Enabling Flakes

Flakes are still considered an experimental feature, so you need to enable them.

  • Temporarily: Add the --experimental-features 'nix-command flakes' flag to any nix command.

  • Permanently (Recommended): Add the following line to your Nix configuration file.

    • On Linux, this is typically /etc/nix/nix.conf.
    • On macOS, it's ~/.config/nix/nix.conf. 
experimental-features = nix-command flakes
Enter fullscreen mode Exit fullscreen mode

3. Devbox

As you can see, Nix and Flakes provide a robust and powerful system for managing development environments. However, this power comes with a significant learning curve. Mastering the Nix language, which is a purely functional language, understanding its evaluation model, and learning the structure of flake.nix can be a daunting task for developers who just want to install Python and get to work.

This is where Devbox comes in. Devbox is a command-line tool that simplifies the creation and management of isolated, reproducible development environments. It uses Nix and Flakes under the hood, but provides a simple, intuitive interface that feels familiar to anyone who has used tools like npm or yarn.

3.1. Devbox Features

  • Reproducible Environments with Nix: Devbox uses Nix to create isolated environments. By specifying dependencies in a devbox.json file, Devbox ensures that all team members and CI/CD systems run the same versions of every dependency.
  • Project-Specific Shell Environments: When you activate a Devbox shell, you enter a dedicated environment where all project-specific dependencies and tools are available, isolated from your system’s global packages. Shell Hooks for Enhanced Customization: Devbox supports shell hooks, which are commands that execute automatically when the environment starts. You can use them to initialize a database, load environment variables, or run setup scripts.
  • Custom Scripts for Task Automation: You can define custom scripts in your devbox.json to automate routine tasks like starting a dev server (devbox run dev), running tests (devbox run test), or building the project.
  • Automatic devcontainer.json Generation for VSCode: Devbox can generate a devcontainer.json file, enabling seamless integration with VSCode’s Dev Containers feature. This is perfect for onboarding new developers or working in containerized setups.
  • Cross-Platform Compatibility: Devbox supports Linux, macOS, and Windows (via WSL), ensuring consistent environments across diverse operating systems.

3.2. Quickstart

Devbox requires the Nix Package Manager. If Nix is not detected when running a command, Devbox will install it for you in single-user mode for Linux.

curl -fsSL https://get.jetify.com/devbox | bash
Enter fullscreen mode Exit fullscreen mode

Or

nix-env -iA nixpkgs.devbox
Enter fullscreen mode Exit fullscreen mode

Or

nix profile install nixpkgs#devbox
Enter fullscreen mode Exit fullscreen mode

Let's see how easy it is to create a deterministic shell with Devbox.

  • Create a new directory and cd to it and initialize devbox: 
mkdir dirbox
cd dirbox
devbox init
Enter fullscreen mode Exit fullscreen mode
  • Add command-line tools. Let's add Python 3.10 and NodeJS 20. You can search for thousands of available packages on Nixhub.io. 
devbox add python@3.10 nodejs@22
Enter fullscreen mode Exit fullscreen mode

Your devbox.json file now tracks these packages:

{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.16.0/.schema/devbox.schema.json",
  "packages": [
    "python@3.10",
    "nodejs@22"
  ],
  "shell": {
    "init_hook": [
      "echo 'Welcome to devbox!' > /dev/null"
    ],
    "scripts": {
      "test": [
        "echo \"Error: no test specified\" && exit 1"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode
  • Start a new shell that has these tools installed: 
devbox shell
Enter fullscreen mode Exit fullscreen mode

Your shell prompt will change to indicate you're in the Devbox shell.

  • Use your favorite tools. The versions you specified are now available in your PATH. 
(devbox) > python --version
Python 3.10.19

(devbox) > node --version
v22.14.0
Enter fullscreen mode Exit fullscreen mode

Your regular system tools and environment variables are also still available.

  • To exit the Devbox shell and return to your regular shell, simply run: 
(devbox) > exit
Enter fullscreen mode Exit fullscreen mode

In just a few commands, you've created a reproducible, isolated development environment without writing a single line of Nix code. Devbox handled the generation of the underlying Nix configuration for you.

4. Automating with Direnv

Devbox makes creating environments easy, but you still have to remember to run devbox shell every time you start working on a project. We can make this even smoother with direnv.

Direnv is an extension for your shell that loads and unloads environment variables depending on your current directory. When you cd into a directory with a .envrc file, direnv automatically executes it, setting up your environment. When you cd out, it cleans up.

4.1. Why Is This Useful?

An isolated environment per project is crucial for several reasons:

  • Dependency Version Mismatching: Your work project might need NodeJS 18, while a personal project uses NodeJS 20. Devbox solves this, and direnv automates switching between them.
  • Application Settings: Environment variables like DATABASE_URL or HTTP_PROXY can be set automatically on a per-project basis.
  • Secrets: API keys and other secrets can be loaded into your environment securely without hardcoding them.
  • Compiler Options: Flags like LDFLAGS or JAVA_HOME can be configured specifically for the project you're working on.

Traditionally, setting up direnv with Nix required writing a custom .envrc file with a command like use nix. This, again, required some knowledge of the Nix ecosystem.

4.2. Automatic Devbox Environments with Direnv

The Devbox team created a seamless integration with direnv that removes this final piece of manual configuration. With this integration, you don't need to write any .envrc files yourself.

Here’s how to set it up:

  • Install direnv 
nix-env -iA nixpkgs.direnv
Enter fullscreen mode Exit fullscreen mode

For direnv to work properly it needs to be hooked into the shell. Each shell has its own extension mechanism.

bash: Add the following line at the end of the ~/.bashrc file:

eval "$(direnv hook bash)"
Enter fullscreen mode Exit fullscreen mode

zsh: Add the following line at the end of the ~/.zshrc file:

eval "$(direnv hook zsh)"
Enter fullscreen mode Exit fullscreen mode
  • In your Devbox project directory, Generate the direnv integration file: 
devbox generate direnv
Enter fullscreen mode Exit fullscreen mode

This command creates a .envrc file with the content use devbox. You'll be prompted by direnv to allow it to run.

direnv allow
Enter fullscreen mode Exit fullscreen mode

That’s it! Now, whenever you cd into your project directory, your Devbox environment will be activated automatically. When you cd out, it will be unloaded. You get a fully automated, reproducible, and isolated development environment with almost zero effort.

References

Nix Mastery: Reproducible Systems and Functional Package Management

Top comments (0)