The local development environment is the piece of infrastructure every engineer touches every day and almost nobody owns. It accumulates by sediment: a version manager someone added years ago, a compose file that covers four of the seven services, a shell script that works if you already have three tools installed, and a README whose first command has been wrong for a year.
Nobody fixes it because it works for everyone currently on the team. Everyone has already paid the setup cost, so the cost is invisible until the next hire pays it again, badly, with two people helping.
There are only three questions worth asking about a local environment setup, and they are not the questions the tools compete on. How long does it take on a machine that has nothing installed. Does it behave the same on every operating system the team uses. And how far does it sit from what actually runs in production.
The third one is the one that gets ignored and the one that costs the most. An environment that is fast and pleasant and lies to you about how the system behaves is not a good environment. It is a bug factory that feels productive.
Key takeaways
- Setup time on a genuinely fresh machine is the only honest measure. Anything measured on a machine that already has the language runtime installed is measuring nothing.
- Cross-platform reliability is usually the reason a setup collapses. A shell script written on one operating system is a per-hire tax on everyone using another.
- Drift from production is the expensive criterion. The bugs that reach production are the ones your local environment could not express, and convenience is usually what removed them.
- Two independent decisions get conflated: how you pin tool versions, and how you run stateful dependencies. Most working setups combine one tool for each rather than finding one tool for both.
The three criteria, and why they trade against each other
Setup time on a fresh machine. Measure it on a machine with nothing on it, following only what is in the repository, with no help from a colleague. Every environment feels fast when measured by someone who already has the runtime, the container engine, the registry credentials and the right shell configuration. The moment you measure it properly, most setups turn out to be an hour of documented steps followed by two hours of undocumented ones.
The structural fix is to make setup a command rather than a document. If the environment is described by a file in the repository and constructed by running something, it is reviewable, versionable and repairable once for everyone. If it is a list of steps in a wiki, every engineer maintains their own divergent copy of it in their head.
Cross-platform reliability. Most teams are mixed: macOS on laptops, Linux in CI and production, and at least one engineer on Windows whose experience determines whether they can contribute at all. A setup that works on one and mostly works on the others is a setup with a permanent support cost.
The reliable pattern is that the environment is Linux everywhere, and the host operating system only has to run a container engine. This costs file system performance on macOS and Windows, which is a real and daily irritation, but it removes an entire class of problem that otherwise reappears with every new hire. The alternative pattern, native execution with exactly pinned tool versions, keeps the performance and requires the tooling to genuinely handle each platform, which is a narrower set of tools than you would hope.
Drift from production. Rank your drift by how likely it is to hide a bug, because they are not equal.
Different language runtime version is the worst, and it is common. The version manager pins it, everyone forgets, and then CI runs something else. Different database engine is close behind: local SQLite against production Postgres hides every dialect difference, every constraint behaviour, every migration hazard, and the hiding is total until deployment.
Missing infrastructure is next. Running without the load balancer, the queue, the CDN, the read replica or the rate limiter means an entire class of behaviour has never been exercised. Concurrency is the sharpest version of this: a local environment with a single process and one user cannot express a race condition that production hits routinely.
Then there is data. An empty or tiny local dataset hides everything about performance, and the query that is instant on twenty rows is the incident on twenty million.
The honest framing is that reducing drift costs convenience, always. The right answer is not to eliminate drift but to be deliberate about which drift you are accepting and to have another layer that catches it, which in practice means CI running against production-shaped dependencies and preview environments exercising the real stack before merge.
Needs first-hand data: Take a machine with nothing installed, hand it to someone who has never worked on the project, and have them follow only what is in the repository while recording a timestamp at every step and every point where they had to ask a question. Do this once per quarter. The list of questions is your defect list, and it is the only reliable way to discover which steps have quietly become wrong.
Devcontainers: a specification, not a product
The devcontainer specification is the closest thing this category has to a standard, and it is worth separating from the products that implement it. It is a JSON file in the repository that describes a base image, additional tooling features, port forwarding, editor extensions and lifecycle commands to run at various points in a container’s life.
What it gives you
- One environment definition, stored with the code, reviewed in pull requests and versioned alongside the thing it builds, which is the property that stops it going stale silently.
- Portability across implementations. The same file is understood by local editor integrations, by a command-line tool and by several cloud development environment products, so the definition survives a change of tooling.
- An end to the operating system split, because development happens inside a Linux container whatever the host is, and the host only needs a container engine.
- Lifecycle hooks that turn setup steps into automation: dependency installation, migrations and seeding run on creation rather than living as instructions someone might misread.
What it does not do
- It does not make the environment fast. A definition that installs everything at creation is slow at every creation; speed comes from a pre-built image published to a registry, which the specification permits but does not do for you.
- It does not manage stateful dependencies well on its own. Databases and brokers need a compose file or equivalent alongside it, and seed data is entirely outside its scope.
- It does not remove drift from production, because the development container is rarely the production image, and nothing in the specification checks that they agree.
- It does not handle secrets. Getting credentials into the container safely is left to each implementation, and the implementations differ.
Adopt it as the definition format. Then choose separately how you run it, and what runs alongside it for state.
Needs first-hand data: Time the same everyday loop on each candidate setup, using your real repository: a cold dependency install, a full test run, and a single-file change through to a reloaded application. Do it on macOS and on Linux, and record the gap between them. The cross-platform gap is the number that decides whether one setup can be standard for the whole team, and it is never in any tool’s documentation.
Nix
Nix is a package manager and build system built around exact reproducibility: packages are described as derivations with all their inputs pinned, and the same description produces the same environment on any machine. A development shell defined in the repository gives every engineer bit-identical tool versions natively, with no container in the path, on both Linux and macOS.
Pros
- Reproducibility is exact rather than approximate, which eliminates the entire family of machine-specific failures rather than reducing them
- Runs natively on the host, so file system performance and tooling behaviour stay normal on macOS instead of paying the container penalty
- The same definitions can produce development shells, CI environments and production images, which collapses drift between them properly rather than by convention
- No vendor, no hosted service and nothing that can be deprecated underneath you
Cons
- The learning curve is the steepest in this article by a distance, and error messages are genuinely difficult to interpret even for experienced engineers
- In practice one or two people understand the configuration, and everyone else is blocked when it breaks, which makes it a single point of failure
- Packaging anything not already in the ecosystem is real work that appears at the worst possible moment
- Half-adoption gives you the complexity without the guarantee, so it is close to an all-or-nothing commitment
Best for: Teams with a committed advocate who need exact reproducibility across mixed macOS and Linux machines and will invest in the learning curve.
Pricing: No vendor and no bill. Open source package manager and ecosystem; the real cost is the engineering time to learn it and to maintain the expressions.
devenv
devenv is a layer on top of Nix that gives you the reproducibility guarantee with a much smaller surface to learn. You declare languages, packages, services and scripts in a compact configuration, and it handles the underlying machinery, including running stateful services such as databases as native processes rather than containers. It is the pragmatic answer to the main objection to Nix.
Pros
- Delivers most of the Nix reproducibility guarantee behind a configuration format an ordinary engineer can read and edit without learning the underlying language
- Runs services such as databases and caches as native processes, which avoids container file system performance problems entirely
- Process management, tasks and pre-commit integration are built in, so the environment covers more than just tool versions
- Sits on the same substrate as Nix, so an advanced team can drop down to the full expression language where necessary
Cons
- Still Nix underneath, so a problem that escapes the abstraction lands you in the hard version anyway
- Smaller community and shorter track record than either Nix itself or the container-based alternatives
- Services running natively behave differently from the containerised versions used in CI and production, which reintroduces a drift you thought you had removed
- Windows support depends on the Linux compatibility layer rather than being native, which is a meaningful constraint on mixed teams
Best for: Teams that want reproducible native environments with declared services and are not prepared to make everyone learn Nix properly.
Pricing: No vendor and no bill. Open source, installed alongside Nix, with an optional commercial cloud service for related use cases that is not required for local development.
Docker Compose
Docker Compose describes services, images, networks and volumes in one file and brings them up together. It is the default answer for stateful dependencies, it is understood by essentially every engineer, and it is the layer most other choices in this article end up sitting on top of rather than replacing.
Pros
- Nearly universal familiarity, so a compose file requires no explanation and a new engineer can debug it without learning anything
- Solves the dependency problem that stops an application being usable locally: database, cache, broker, object storage, all started by one command
- Uses the same container images as CI and frequently as production, which keeps engine and version drift small where it matters most
- The same file often serves integration testing and ephemeral environments, so the maintenance is amortised across more than one use
Cons
- File system performance on macOS and Windows is materially worse than native, and it is a daily cost rather than an occasional one
- Compose configuration is not production configuration for most teams, so topology, networking and resource behaviour still diverge
- Seed data is outside its scope, so a fresh environment gives you running services and an empty database unless someone maintains a script
- Compose files rot quietly, because the engineer who changes one service rarely runs the whole stack locally
Best for: Any team whose application needs real stateful dependencies locally, as the base layer beneath whichever version-pinning tool they choose.
Pricing: No charge for the compose tooling itself; the container runtime it depends on is free for personal and small-business use with paid subscriptions required at larger organisations.
mise
mise is a fast polyglot tool version manager that reads a configuration file in the repository and installs and activates the declared versions of every runtime and command-line tool the project needs. It also handles environment variables and project-scoped tasks, which means a single file can pin the toolchain, set the configuration and define the commands, replacing three separate mechanisms.
Pros
- One file pins every runtime and tool version for the project, which removes the most common and most damaging source of drift
- Activation is fast enough not to be noticeable in a shell prompt, which matters because a slow version manager gets disabled
- Environment variables and project tasks in the same file mean the repository describes not just the tools but how to run things
- Compatible with the configuration formats of older version managers, so migration is incremental rather than a rewrite
Cons
- Manages tools, not services, so databases and brokers are a separate problem entirely
- Reproducibility is version-level rather than exact, so two machines with the same declared versions can still differ in system libraries
- Shell integration means it is in the path of every new shell, and a bad interaction with a shell configuration is confusing to debug
- Younger than the alternative it replaces, so some tool plugins are less battle-tested
Best for: Polyglot teams who want tool versions pinned in the repository with minimal ceremony, paired with a container setup for stateful services.
Pricing: No vendor and no bill. Open source, installed from common package managers, with no service component.
asdf
asdf is the long-standing polyglot version manager that established this pattern: a single tool with per-language plugins, reading a version file from the repository and switching runtimes per directory. It is slower and more manual than its successor but it has a very long track record and an enormous plugin catalogue, including runtimes and tools that nothing else supports.
Pros
- Very large plugin ecosystem covering obscure runtimes and tools that newer managers have not packaged
- Long track record and wide familiarity, so its behaviour is well understood and well documented across communities
- Single mechanism for every language removes the need for separate per-language version managers and their conflicting shell hooks
- Version file in the repository makes the required versions explicit and reviewable rather than tribal
Cons
- Shim-based activation adds noticeable overhead to command invocation, which is felt constantly in scripts and test runs
- Plugins are community-maintained with uneven quality, and a broken plugin blocks the runtime it manages
- Manages tools only, with nothing to say about services, environment variables or tasks
- Largely superseded in new projects by faster alternatives, so momentum is against it
Best for: Existing setups already standardised on it, and teams needing a runtime whose only available plugin lives in this ecosystem.
Pricing: No vendor and no bill. Open source, installed from a package manager or by cloning it, with community-maintained plugins.
Tilt
Tilt is for the case where local development means a Kubernetes cluster. It watches your source, rebuilds and redeploys the affected services into a local or remote cluster, live-updates files into running containers where a full rebuild is unnecessary, and presents the whole multi-service state in one view with logs and health. It exists because the inner loop on Kubernetes is otherwise unbearable.
Pros
- Makes an inner development loop on Kubernetes actually workable by rebuilding and redeploying only what changed
- Live update syncs files directly into running containers, which removes the image build from the common edit-and-see cycle
- One interface showing every service, its logs and its health, which is a substantial improvement over many terminal windows and manual kubectl
- Because it deploys your real manifests, local behaviour stays close to production rather than being a translated approximation
Cons
- Requires a Kubernetes cluster and someone who can operate it, which is a large cost if you were not already on Kubernetes
- Resource consumption on a laptop running a real cluster plus your services is significant and pushes many teams to remote clusters
- Configuration is written in a scripting dialect that becomes its own maintained artefact as the service count grows
- Complete overkill for an application that is not deployed on Kubernetes
Best for: Teams already running Kubernetes in production who want a local loop that uses the same manifests instead of a divergent compose file.
Pricing: No vendor and no bill for the tool. Open source under a permissive licence; the cost is the cluster resources, local or remote, that it deploys into.
Skaffold
Skaffold solves the same Kubernetes inner-loop problem with a different emphasis: it is a declarative pipeline covering build, push, deploy and debug, configured in YAML, and designed to be used identically in local development and in CI. That symmetry is its argument. The same configuration that runs your local loop can run your continuous integration, so the two cannot drift.
Pros
- One declarative configuration for local development and CI, which removes drift between what you run and what the pipeline runs
- Pluggable across build tools and deployment mechanisms, including Helm and Kustomize, so it fits existing Kubernetes practice
- Built-in debugging support that attaches language debuggers to containers running in the cluster, which is otherwise painful to set up
- File sync for interpreted languages avoids a full image rebuild on every edit
Cons
- YAML configuration becomes long and awkward for complex multi-service setups, and there is no escape into a real programming language
- Still requires a Kubernetes cluster and the operational knowledge that implies
- The feedback interface is less immediate and less informative than the alternative built around a live dashboard
- Getting the file sync and build configuration right for every service is real up-front work before the loop feels fast
Best for: Kubernetes teams who want the same declarative build-and-deploy configuration used by developers locally and by the CI pipeline.
Pricing: No vendor and no bill for the tool. Open source; cost is the cluster and registry infrastructure it builds into and deploys against.
Orbstack
Orbstack is a container and Linux virtual machine runtime for macOS built for speed and low resource consumption, positioned as a replacement for the default container engine on that platform. For teams whose local environment is container-based, it addresses the single loudest complaint about that approach, which is that containers on macOS are slow and drain the battery.
Pros
- Noticeably faster file system and network performance for containers on macOS than the default runtime, which is the main daily pain of container-based development
- Lower resource and battery consumption, which matters because a local stack that flattens a laptop gets avoided
- Drop-in compatibility with existing container tooling and compose files, so adoption requires no changes to the repository
- Also runs full Linux virtual machines, which is useful for reproducing production behaviour that a container cannot express
Cons
- macOS only, so a mixed team gets an inconsistent story and the benefit cannot be standardised across everyone
- Commercial product rather than an open-source component, which introduces a vendor dependency in the development path
- Does not change what your environment contains, only how fast it runs, so it fixes none of the drift or reproducibility problems
- Per-seat licensing for commercial use is another purchase to justify for something that has a free default alternative
Best for: macOS-heavy teams already committed to container-based local development who want the performance complaint to go away.
Pricing: Free for personal and non-commercial use, then per-seat subscription tiers for commercial use, with no infrastructure cost since it runs locally.
How to choose
Treat this as two separate decisions, because trying to solve both with one tool is where setups get baroque.
Decision one: how tool versions are pinned. If your environment is container-based, the image pins them and you need nothing else. If it is native, use mise, or asdf if you are already on it and it works. If exact reproducibility genuinely matters and you have someone who will own it, Nix or devenv.
Decision two: how stateful dependencies run. Docker Compose for almost everyone. devenv if you have chosen the Nix path and want native services. Tilt or Skaffold only if you are already on Kubernetes, in which case pick Tilt for the better interactive loop and Skaffold for configuration shared with CI.
Then layer the devcontainer specification over whichever combination you chose, so the definition lives in the repository and works both locally and in a cloud environment. On macOS, add Orbstack if container performance is the loudest complaint, and recognise that it is a comfort improvement rather than a correctness one.
Finally, decide explicitly which production drift you are accepting. Write it down in the repository: same database engine and major version, yes; same concurrency model, no; realistic data volume, no, covered by a load test. A written list makes the gaps visible, and visible gaps get covered by preview environments and CI instead of being discovered in production.
| Tool | What it solves | Reproducibility | Platforms | Picks itself when |
|---|---|---|---|---|
| Devcontainers (specification, not a product) | Environment definition | Image-level | Anywhere implemented | You want the definition in the repository |
| Nix | Tools and full environments | Exact | macOS and Linux | Exactness is worth the learning curve |
| devenv | Tools and native services | Near-exact | macOS and Linux | You want Nix without teaching Nix |
| Docker Compose | Stateful dependencies | Image-level | All, with performance cost | The app needs a real database locally |
| mise | Tool versions | Version-level | All | Polyglot repository, minimal ceremony |
| asdf | Tool versions | Version-level | All | An existing setup already uses it |
| Tilt | Kubernetes inner loop | Manifest-level | All | Already on Kubernetes, want fast feedback |
| Skaffold | Kubernetes build and deploy | Manifest-level | All | The same config should run in CI |
| Orbstack | Container performance on macOS | No change | macOS only | Containers on macOS are the complaint |
Frequently asked questions
Should local development use containers or run natively?
Containers if your team is on mixed operating systems or your application has several stateful dependencies, because the consistency is worth the performance cost and the alternative is an open-ended support burden. Native if your stack is a single language with few dependencies and file system performance genuinely matters to your feedback loop. The hybrid that many teams settle on is the pragmatic answer: application code native with pinned versions, dependencies in containers. That gets you fast iteration where you edit and realistic services where you integrate.
How close should a local environment be to production?
Close on the things that hide bugs, and not close on the things that only cost time. Same database engine and major version is non-negotiable, because dialect and constraint differences are invisible until deployment. Same language runtime version, likewise. Realistic data volume, concurrency and network topology are all valuable and all expensive, and they are better covered by CI against production-shaped dependencies and by preview environments than by making every laptop heavier. Decide the list deliberately and write it down rather than letting it happen by accident.
Is Nix worth the learning curve?
Only with a committed advocate who will own the configuration, and only if you have actually been hurt by reproducibility problems. The guarantee it provides is real and nothing else offers it. The failure mode is equally real: the person who understands the expressions becomes a bottleneck, and everyone else experiences the tool as an opaque thing that occasionally blocks them. devenv narrows that gap considerably and is the better starting point for most teams considering this path.
What is the difference between a devcontainer and a cloud development environment?
A devcontainer is a specification describing an environment; a cloud development environment is a product that runs one on someone else’s infrastructure. The same devcontainer definition can run on your laptop or in a hosted workspace, which is the reason to adopt the specification regardless of where you eventually run it. The hosted option removes setup time and adds latency, cost and an offline gap, which is worked through in cloud development environments.
How do I stop the local setup from breaking every few months?
Make it a build artefact rather than a document, so it is exercised and reviewed like code. Run the fresh-machine setup in CI on a schedule so a broken step fails visibly rather than being discovered by the next hire. Give the environment definition an owner in the same way any other shared component has one. And measure the setup on a genuinely clean machine each quarter, because that is the only way to find the steps that quietly became wrong, as covered in developer onboarding tools.
Related reading
- Best AI coding assistants — the other half of the inner loop, once the environment actually runs.
- Best cloud development environments — removing local setup entirely, and what that costs.
- Best developer onboarding tools — measuring whether any of this actually shortened the first week.
- Best preview environment tools — where the production drift you accepted locally gets caught.
- Best container registries — image pull latency, which is most of a container-based setup time.
- Best terminal and shell tools for developers — the layer everything here is driven from.