Nix shells vs dev containers for mixed team onboarding

Why onboarding breaks on mixed machines

Most setup problems start before a new developer writes a line of code. Two laptops can look the same on a video call and still behave very differently. Package managers change. Shells load different config files. File paths, permissions, and CPU architecture all matter. A setup guide that works on one Mac can fail on Ubuntu, and Windows with WSL adds another layer.

Teams usually notice the problem too late. The README says "install Node.js, Postgres, and Redis," but it leaves out the parts that actually trip people up: versions, shell profiles, OS-specific package names, and small differences in default tools. One developer uses Homebrew, another uses apt, another reaches for Docker, and each choice changes what happens next.

Shell behavior causes more trouble than most teams expect. A command that runs in zsh can fail in bash because an alias is missing, an environment variable loads from a different file, or a script assumes GNU tools that macOS does not ship by default. Fish users get their own set of paper cuts.

Editors can hide these problems for a while. A project opens fine in VS Code or a JetBrains IDE, autocomplete works, and the folder looks healthy. Then the first build fails because a CLI is missing, the test runner calls the wrong binary, or the editor terminal uses a different shell from the one the developer configured earlier.

New hires feel this first. Instead of fixing a small bug on day one, they lose hours to PATH issues, OpenSSL mismatches, native dependency errors, and version conflicts that have nothing to do with the product. It is frustrating, and it makes the team look less organized than it probably is.

Small product teams see the pattern quickly. One engineer on Apple Silicon gets one result, another on Intel gets another, and a contractor on Linux hits compile errors nobody else can reproduce. When onboarding depends on machine history, every new laptop turns into a support ticket. Senior engineers end up doing help desk work instead of building the product.

How Nix shells work in plain words

A Nix shell is a shared recipe for the tools a project needs at the command line. The team keeps that recipe in the repository, often in shell.nix or flake.nix. It can pin exact versions of Node.js, Go, Python, pnpm, Terraform, and other tools the project depends on.

When a developer enters that shell, Nix downloads or builds those versions and exposes them in the terminal. If the file asks for Node.js 20 and a specific database client, everyone gets that same setup. Teams often place environment variables there too, so the shell opens with the same PATH and the same basic settings.

The shell mostly affects terminal work, not the whole computer. Your editor still runs on your laptop. So do your browser, Git app, password manager, and other desktop tools. That is one reason Nix can feel lighter than moving the entire project into another runtime.

This style works best for teams that already do a lot through commands. If people start the app, run tests, format code, or seed data from the terminal, a shared shell gives them one common base without forcing everyone into the same editor. One person can use Vim, another can use VS Code, and both still call the same project tools.

A mixed team with Macs and Linux laptops might keep one Nix file that pins Go, Node.js, and a few database utilities. A new hire clones the repo, enters the shell, and runs the same commands as everyone else. The first setup can take a little time because Nix has to fetch packages, but the daily routine is simple after that: open the project, enter the shell, and work.

How dev containers work in plain words

A dev container puts the project tools inside a Docker image. Instead of asking every new hire to install the right version of Node.js, Python, database clients, and shell utilities on their own laptop, the team defines that setup once and keeps it with the project.

The editor then connects to that container and works inside it. When someone runs install, test, lint, or build commands, those commands run in the container rather than on the host machine. That helps when one person uses macOS, another uses Windows, and someone else works on Linux.

For onboarding, this usually means people start from a template instead of a long setup document. A new hire pulls the repository, starts Docker, opens the folder in a supported editor, and lets the editor attach to the container. If the template is solid, they can reach the first successful build without hunting for missing packages.

Most dev container setups include a base image, workspace settings, environment variables, startup commands, and sometimes extra services like Postgres, Redis, or a message queue. That cuts down on the usual "it works on my machine" problem. If the image stays the same, the project behaves much more consistently across mixed local environments.

There is a tradeoff. Docker becomes part of daily work from the first day. People need enough disk space for images, enough memory for services, and a basic feel for logs, rebuilds, and port mapping. When Docker is slow, the whole project feels slow.

This approach fits projects that depend on many system packages or background services. It is often the practical choice when a team wants one repeatable setup and does not mind carrying more overhead on every laptop.

Startup cost: first setup and daily overhead

The first hour matters, but the second week matters more. Teams often judge setup options by a quick demo: "I opened a shell" or "the container started." That misses where time usually goes.

Nix shells often ask for more patience before the first win. A new teammate has to install Nix, get used to a different model, and read files that can look strange if they have only used Homebrew, apt, or shell scripts. The payoff can be strong, but day one is rarely smooth for beginners.

Dev containers feel easier at first because Docker is already familiar to many teams. Still, the cost shows up quickly: image pulls, long builds, permission quirks on some machines, and a surprising amount of disk use. On a laptop with limited space, one project can quietly turn into several gigabytes.

Cold start time matters more than shell entry after day one. If a new hire waits 20 minutes for the first working environment, that shapes the whole impression. After that, shaving a second off "enter shell" is nice, but it does not change much.

Daily overhead mostly comes from change. When someone adds a system package, updates a language version, or tweaks a service, the waiting time shows up right away. Nix tends to feel better after the cache is warm. Dev containers feel better after the image is built. Both feel slow when dependencies change every few days. Both feel fine when the stack stays stable for weeks.

Offline work also differs. Nix can work well once the needed packages already exist in the local store, but adding something new without network access can stop you. Dev containers can run offline too if the image and layers already sit on the machine, but a missing base image or rebuild sends you back to the network.

A small team should test three moments, not one: first setup on a clean laptop, one dependency change during the week, and one day with weak internet. That tells you far more than a polished demo.

Reproducibility: what stays the same and what drifts

Reproducibility sounds simple: two developers open the same project and get the same result. In mixed local environments, it usually breaks in smaller ways first. One laptop has a newer Node.js version. Another has a different SSL library. One person runs tests in a terminal, another runs them through an editor plugin. The repo matches, but the behavior does not.

Nix usually gives tighter control over exact package versions. If the team pins dependencies in its Nix files and keeps those files current, the shell can make macOS and Linux machines behave much closer to each other. Compilers, CLIs, and system packages come from the same definition. That removes a lot of random breakage.

Nix still relies on discipline. Developers need to enter the shell and use the tools inside it. If someone grabs a globally installed formatter or test runner, drift starts quickly.

Dev containers solve the problem differently. They freeze the image, so the runtime, libraries, and shell tools inside that image stay consistent. That helps a lot, especially for teams that already work in Docker and VS Code. But the container is not the whole machine. Project files usually come from the host through a mounted folder, and host details can still leak in through permissions, file watching, SSH keys, and editor behavior.

Where drift usually sneaks in

Most teams lose reproducibility in the same places:

• global tools outside the shell or container
• editor extensions that call host binaries
• host-specific file permissions and line endings
• secrets, certificates, or SSH config that differ by machine
• CI jobs that use a different setup than local development

That last point matters a lot. If developers use Nix locally but CI installs packages another way, the promise breaks. If developers use a dev container but CI runs a different base image, the promise also breaks. You do not need a perfect setup. You need the same setup in both places.

For strict dependency pinning, Nix usually wins. For a fully packaged workspace, dev containers often feel easier. In both cases, reproducibility ends the moment the team steps outside the chosen setup.

Editor fit: terminal habits and IDE habits

If your team spends most of the day in a terminal, Nix often feels more natural. People can open the same shell in iTerm, Terminal, Kitty, or a Linux console and run the same commands. That matches teams who already use Make, npm scripts, Go tools, Python wrappers, or plain CLI test runners.

Dev containers usually fit better when the editor is the center of daily work. A developer opens the project in VS Code, the container starts, and the editor attaches to that environment. For people who expect one-click debugging, built-in terminals, and extensions that behave the same way every day, that removes a lot of guesswork.

This is where the choice becomes less about theory and more about habit. A small speed win does not help much if half the team fights the editor every morning.

Nix keeps the environment consistent, but the editor still lives on the host machine unless you add more setup. That is fine for terminal-first developers. It can feel awkward for people who want their linter, language server, debugger, and test runner to all come alive inside the editor with no extra steps.

Dev containers smooth out that editor story, but they change how tools behave. Debuggers may need container-aware settings. File watchers can slow down on Docker bind mounts, especially on macOS and Windows. Some extensions work well only when they run inside the container, while others still depend on host tools or local credentials.

Before picking a default, check four things: where people run most commands, which debugger flows they use every week, whether file watching stays fast enough on their laptops, and which editors they refuse to give up. Editor preference can outweigh a modest setup difference.

If most developers live in VS Code and depend on container-aware extensions, dev containers usually cause less friction. If the team uses different editors, shares terminal commands in chat, and treats the editor as a personal choice, Nix usually gives everyone more freedom.

A split setup can work too. Some teams use Nix to define the tools, then let editor-focused developers wrap that setup in a dev container when they need it. That keeps the command line stable without forcing one editor habit on everyone.

How to choose step by step

Choose based on the machines and habits you already have, not on whichever setup looks cleaner in a demo. In mixed local environments, the best option is usually the one that fails in the fewest boring ways on the laptops people already own.

Start with a short audit. If half the team uses Linux, two people use macOS, and one person works inside Windows with WSL, that matters more than abstract arguments about purity. Write down the devices, the editors, and the tools that usually break during setup. Teams often argue about package management when the real pain comes from debugger setup, language servers, or one missing system library.

Then run a small test:

1. List the machines and operating systems the team actually uses, including older laptops.
2. Note the setup failures that keep repeating. Compilers, database clients, test runners, and local secrets handling are common trouble spots.
3. Time a clean install for both options on a fresh machine. Measure the first setup and the next morning's startup.
4. Test the daily workflow in the editors people already use. Run debugging, formatting, tests, and linting, not just "it starts."
5. Pick one default path and keep one fallback for edge cases.

A small team can learn a lot from one honest trial. If Nix installs fast and works well in the terminal, but two developers lose half a day getting breakpoints to work in their IDE, that cost is real. If dev containers give everyone the same editor setup but feel slow on older machines, that cost is real too.

The decision often comes down to one plain question: where do you want the complexity to live? Nix puts more of it into environment definition on the host. Dev containers put more of it into Docker, images, and editor integration. Pick the one your team can maintain without calling the same person every week.

A simple example from a small product team

The difference becomes easier to see with a real team in mind. Picture a startup with four developers: two on MacBooks, one on a Windows laptop, and one on a Linux box. They share one product, but they do not share the same local setup problems.

Most backend work happens in the terminal. The team spends hours running test commands, database tools, code generation, linters, and small scripts. For that part, they use a Nix shell. It gives everyone the same CLI tools and versions, no matter which machine they use. A new developer opens the repo, enters the shell, and can run the backend commands without hunting for package managers or fixing version drift.

The frontend feels different. Daily work depends on editor extensions, browser debugging, and a Node.js setup that matches the app exactly. One service also has enough local quirks that Windows turns setup into a chore. The team puts that service in a dev container instead. The editor opens inside the container, the workspace extensions match, and the browser debugging flow stays predictable.

Where the line sits

The team writes down the boundary in plain language. Nix covers the shared terminal tools used across the repo. The dev container covers the one service that needs tighter editor and OS control. Browsers, the editor itself, and Docker stay outside that boundary.

That short note saves time. Without it, one developer tries to force everything through Nix, another expects the container to solve every setup issue, and the next hire has no idea which path to follow.

This split works because it matches how people actually work. Backend developers keep a fast terminal workflow. Frontend developers keep the editor experience they need. The team does maintain two setup paths, which is extra work, but each path has a clear job.

In mixed local environments, that clarity matters more than purity. When each tool has a defined start and stop point, onboarding gets faster and daily work feels less fragile.

Mistakes that waste time

Teams comparing these two options often lose hours on one simple mistake: they keep both in the same repo without picking a default. That sounds flexible, but it usually creates two half-maintained paths. One person updates the Nix file, another tweaks the container, and new hires have to guess which setup the team actually trusts.

Another trap is forcing Docker on everyone. If a developer only needs a language runtime, one database client, and a couple of CLIs, a full container stack can feel heavy. Image pulls, volume mounts, and slow file sync add friction before the first line of real work.

Windows gets ignored more often than teams admit. Path rules, line endings, file permissions, and mount speed can turn a clean setup doc into a dead end. A repo that feels smooth on macOS can crawl on Windows when the container watches thousands of files. If your team has even one Windows laptop, test early on a real machine.

Version drift causes quieter damage. Loose pins feel convenient until a package update changes behavior on a random Tuesday. Then two developers both claim they followed the same steps, and both are right. Pin the versions that matter, whether that means Nix inputs, base images, language runtimes, or package manager lockfiles.

The best onboarding check is not a screenshot of a shell prompt or a running container. It is task completion. A simple test works better than any setup checklist: clone the repo on a fresh machine, start the environment once, open the project in the editor the developer actually uses, run tests or the app locally, then make one small change and commit it.

If that flow breaks, onboarding is not done. A mixed team does not need perfect theory. It needs one clear default, one honest set of exceptions, and a setup that gets a new person to the first real task without drama.

How to test your choice

The fastest way to settle the question is to watch one new person set up the project from scratch. Use a machine that matches the real team setup, not the clean laptop a senior engineer keeps for demos.

Ask that person to get the app running the way they would on day one. Measure the parts that usually cause friction, not just the final success: time to first build, time to first test pass, time to first debug run, and the number of manual fixes or private tips needed.

Count every side chat, missing secret, editor plugin, and local patch. If someone has to say, "skip that step" or "install this one extra thing," your onboarding still has drift.

Keep setup notes short enough that a new hire can finish them without a live guide. If the notes turn into a long checklist with special cases, the process is too brittle. Most teams do better with a short path that works on a real machine than with a perfect document nobody can follow alone.

Review the choice again when the stack changes, the team grows, or editor habits shift. A small team using one editor may feel fine with dev containers now. Later, if people spread across terminals, JetBrains tools, and different local setups, Nix may reduce friction. The opposite can happen too if container-based debugging becomes the everyday habit.

A small product team can test this in one afternoon. Pick one Mac, one Linux laptop, and one Windows machine if that matches the team. Run the same onboarding flow on all three. The pattern usually shows up fast.

If the results still look messy after a cleanup pass, outside help can save time. Oleg Sotnikov at oleg.is works with startups and small companies on onboarding flow, infrastructure, and technical leadership, so a short review can help teams choose a setup they can actually maintain.