TL;DR:

  • Devbox is a CLI tool that creates isolated, reproducible shell environments using Nix packages, without requiring you to write Nix code
  • Each project gets a devbox.json file that pins exact package versions, which any team member can reproduce with devbox shell
  • It generates Dockerfiles and devcontainer.json automatically, bridging local dev and CI/container environments

The reproducible development environment problem is old. You install Node 18, your colleague has Node 20, CI runs on 22, and half your afternoon disappears tracking down a behavioural difference that has nothing to do with your actual code. asdf helps. Docker helps more. Neither is frictionless.

Devbox sits in a different position. It uses Nix as its package backend, which means access to over 100,000 packages at pinned versions, but exposes a simple CLI rather than the Nix language. You get Nix’s reproducibility without Nix’s learning curve.

Installing Devbox

curl -fsSL https://get.jetify.com/devbox | bash

That installs Nix if it’s not already present, then installs the Devbox CLI. On macOS and Linux. No Windows native support yet, though WSL2 works.

Initialising a Project

In your project directory:

devbox init

This creates a devbox.json file:

{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.12.0/.schema/devbox.schema.json",
  "packages": [],
  "shell": {
    "init_hook": [],
    "scripts": {}
  }
}

You then add packages. Packages come from Nixpkgs, so there are a lot of them:

devbox add nodejs@20 python@3.12 postgresql@16 redis

The packages are resolved to specific Nixpkgs commits and written to devbox.json. Anyone on your team who runs devbox shell gets exactly those versions, regardless of what’s installed on their system.

Entering the Shell

devbox shell

This drops you into a shell where only the packages defined in devbox.json are available in $PATH. Your global system packages are still there but don’t interfere. Exit the shell with exit or Ctrl-D and you’re back to your normal environment.

The isolation model is more like a virtualenv than a container: it’s the same OS, same filesystem, but a scoped PATH. Startup is fast compared to spinning up a Docker container.

Running Commands Without Entering the Shell

devbox run node --version
devbox run python3 -c "import sys; print(sys.version)"

Or define named scripts in devbox.json:

{
  "shell": {
    "scripts": {
      "start": "node server.js",
      "test": "pytest tests/",
      "db:migrate": "python manage.py migrate"
    }
  }
}

Then run devbox run start, devbox run test, etc.

Direnv Integration

The workflow becomes hands-free with direnv. Devbox can generate a .envrc file:

devbox generate direnv

Now when you cd into the project directory, the devbox environment activates automatically. Change directory out, and it deactivates. No manual devbox shell required.

Generating a Dockerfile

devbox generate dockerfile

This produces a Dockerfile that uses the same packages defined in devbox.json. It’s not always perfectly optimised for production images, but it’s a solid starting point and ensures consistency between local dev and CI.

Dev Container Support

devbox generate devcontainer

Generates .devcontainer/devcontainer.json and a matching Dockerfile. This makes your project compatible with VS Code Dev Containers and GitHub Codespaces, both of which read the devcontainer spec.

When Devbox Beats the Alternatives

Vs. Docker for local dev: Devbox is faster to enter, uses less memory, and doesn’t require a running Docker daemon. The tradeoff is that you’re not fully isolating the OS, so OS-level differences between macOS and Linux can still affect you.

Vs. asdf/mise: Devbox has a larger package selection (anything in Nixpkgs, not just language runtimes) and better version pinning. mise is faster for the things it supports and has better shell integration; for runtime version management specifically, it’s competitive. Devbox wins when you need non-runtime tools (databases, CLIs, build tools) alongside your language runtimes.

Vs. Nix directly: You don’t have to learn Nix. If you already know Nix and need full control over derivations, use Nix directly. If you want the benefits without the syntax, Devbox is the on-ramp.

Caveats

Not everything in Nixpkgs builds cleanly on macOS. Apple Silicon support has improved a lot in recent Nixpkgs releases, but you’ll occasionally hit packages that only work on Linux. The devbox team maintains a list of packages with known issues.

Package search is available at search.nixos.org. The package names don’t always match what you’d expect from Homebrew or apt, so you may need to look up the correct Nixpkgs attribute name.

A Practical Setup

For a Python web project with PostgreSQL:

devbox init
devbox add python@3.12 uv postgresql@16
devbox generate direnv
echo 'POSTGRES_HOST=localhost' >> .env

The devbox.json is committed to version control. New team members run devbox shell, or just cd into the directory with direnv, and they have the exact same Python 3.12, uv, and PostgreSQL 16 without touching their global environment.

That’s the pitch. The more diverse your tech stack, the more time this saves.

References