Two developers clone the same repository. Both follow its README. One runs Python 3.13 against PostgreSQL 17; the other has Python 3.12, a different libpq, and a database left over from last week’s branch. The application starts on both machines, but only one passes the tests.
There is no single “dependency problem” here. The Python packages, interpreter, native libraries, database server, database contents, and test commands are independent sources of variation. A package manager can eliminate some of them while leaving others untouched.
The useful question is not whether an environment is reproducible. It is which inputs are controlled, which are still mutable, and how another machine proves it received the intended environment. This is the lens through which Nix and devenv become interesting.
The cover is a credited external photograph used as a visual reference, not a Nix or devenv screenshot. The original technical cover illustration appears below in the article, alongside published upstream demonstrations and a conference recording—references to inspect, not output of the example in this article.
Reproducibility has more than one boundary
“Reproducible” often compresses several distinct claims:
- Dependency resolution: the same declared package inputs resolve to the intended versions and artifacts.
- Build environment: the compiler, interpreter, system libraries, and relevant build inputs are controlled.
- Runtime behavior: the application sees equivalent configuration, services, clocks, filesystem state, and outside systems.
- Build output: two independent builds produce identical bytes. This is a stronger claim than getting matching package versions.
A successful pip install, or even a committed Python lockfile, establishes none of these in isolation. Nor does Nix automatically guarantee bit-for-bit output: nondeterministic timestamps or build steps can survive a well-specified dependency graph. Nix’s sandbox reduces accidental access to host inputs, but it does not turn arbitrary software into deterministic software. See the Nix manual on build isolation.
Nix is the foundation, not the whole workflow
Nix provides a package manager and a build model built around declared inputs and the /nix/store. A derivation describes how a result should be built; store paths let multiple versions and dependency variants coexist without replacing a single system-wide installation. nixpkgs is a package collection, not a synonym for Nix or NixOS. NixOS is a separate operating system built on related machinery.
Pinning a revision of nixpkgs matters. Asking for the moving nixpkgs-unstable branch twice, months apart, can resolve to different commits. A lockfile records the resolved revision so a teammate can attempt to use that input graph rather than whatever the branch points to today. Binary caches can provide prebuilt store objects for that graph instead of compiling everything locally; they are an acceleration and distribution mechanism, not proof of runtime equivalence. Nix’s substituter documentation explains the trust model.
A plain nix develop shell may be all a small project needs. You can also use Nix flakes, whose flake.lock pins flake inputs. Flakes are not a prerequisite for using Nix, and flake.lock is not the lockfile used by a regular devenv project. devenv has its own input model and devenv.lock; it sits above Nix rather than replacing it. See devenv inputs and Nix flakes.
What devenv adds
Once a project needs more than a compiler or interpreter, the development shell becomes a small local platform. devenv gives that platform an explicit model: packages, language integrations, environment variables, processes, service definitions, tasks, tests, and lifecycle hooks. In devenv 2.x, its native Rust process manager is the default; older process-compose tutorials should not be copied without checking the 2.0 migration guide.
Original GIF · Release explanation
The division of responsibility is concrete:
| File | Responsibility | What it does not pin |
|---|---|---|
devenv.nix | Project tools, languages, services, tasks, checks | The revisions of all inputs by itself |
devenv.yaml | Input references, imports, CLI compatibility rule | Resolved input commits by itself |
devenv.lock | Resolved devenv/Nix inputs | PyPI dependencies or database rows |
pyproject.toml | Python project metadata and dependency constraints | An exact resolved Python environment by itself |
uv.lock | Python dependency resolution and artifacts | PostgreSQL data, host kernel, or secrets |
devenv update deliberately refreshes the Nix input graph. That is a maintenance operation, not something to run implicitly in a supposedly frozen CI build. devenv’s file reference describes the respective configuration files.
A small service with two lockfiles
Consider a FastAPI health endpoint backed by a local PostgreSQL service, with Ruff and Pytest for checks. The demo is intentionally small: its purpose is to expose boundaries rather than to benchmark a framework.
Verification status: the configuration below combines documented devenv 2.x and uv features, but the complete combination has not been executed for this article. Treat it as an implementation candidate, not a measured or compatibility-certified template. In particular, the database connection and process readiness need to be confirmed on a real Nix host.
The intended repository layout is:
reproducible-python-demo/
├── devenv.nix
├── devenv.yaml
├── devenv.lock # generated, then committed
├── pyproject.toml
├── uv.lock # generated, then committed
├── app/
│ ├── __init__.py
│ └── main.py
└── tests/
├── test_health.py
└── test_database.py
1. Declare the Nix inputs
devenv.yaml starts with a reference that will be resolved into devenv.lock:
# devenv.yaml
inputs:
nixpkgs:
url: github:NixOS/nixpkgs/nixpkgs-unstable
# A compatibility floor, not an exact CLI version pin.
require_version: ">=2.4"
The URL above is a moving branch until devenv.lock records a resolution. The version rule checks compatibility; it does not fix which devenv CLI binary a developer installs. For a fully validated demo, record and enforce the exact CLI version actually tested. Do not invent a devenv.lock manually: it must be generated by devenv and committed with the project.
2. Describe the shell, service, and checks
The following devenv.nix proposes a single Python interpreter supplied by Nix, uv for Python dependencies, PostgreSQL as a local service, and named tasks:
# devenv.nix — documented API composition; end-to-end untested
{ config, pkgs, ... }:
{
packages = [ pkgs.git pkgs.curl pkgs.postgresql ];
languages.python = {
enable = true;
package = pkgs.python313;
venv.enable = true;
uv = {
enable = true;
sync.enable = true;
sync.arguments = [ "--locked" ];
};
};
services.postgres = {
enable = true;
initialDatabases = [ { name = "demo"; user = "postgres"; } ];
};
# A Unix socket in this example, not a publicly reachable DB.
env.DATABASE_URL = "postgresql://postgres@/demo?host=${config.env.PGHOST}";
tasks."app:lint" = {
after = [ "devenv:python:uv" ];
exec = "uv run --locked ruff check .";
};
tasks."app:test" = {
after = [ "devenv:python:uv" ];
exec = "uv run --locked pytest -q";
};
tasks."app:serve" = {
after = [ "devenv:python:uv" ];
exec = "uv run --locked uvicorn app.main:app --host 127.0.0.1 --port 8000";
};
# The test lifecycle starts configured processes (including PostgreSQL).
enterTest = ''
uv run --locked ruff check .
uv run --locked pytest -q
'';
}
Original GIF · Release explanation
The Python integration documents both uv synchronization and the dependency on devenv:python:uv for tasks: devenv tasks run does not automatically execute all shell-entry tasks. The PostgreSQL module documents initialDatabases, and the test lifecycle starts enabled processes before tests. Whether the PostgreSQL socket is reachable when the first connection is attempted is a practical readiness assertion to test, not an output to assume.
There is a subtle security and correctness reason to keep the DATABASE_URL local to the service: opening PostgreSQL on all interfaces just to make a demo easier introduces an unrelated attack surface. A secret database password, if the deployment needs one, belongs in a runtime secret provider—not in the Nix expression or the store. devenv’s secrets guidance covers that distinction.
3. Lock the Python graph separately
For pyproject.toml, declare the dependencies without pretending a version range is a complete lock:
[project]
name = "reproducible-python-demo"
version = "0.1.0"
requires-python = ">=3.13,<3.14"
dependencies = [
"fastapi",
"uvicorn",
"psycopg[binary]",
]
[dependency-groups]
dev = ["pytest", "ruff", "httpx"]
The first bootstrap has an unavoidable ordering constraint: the checked-in configuration above demands uv.lock before automatic synchronization begins. To generate the locks for a new demo, temporarily change languages.python.uv.sync.enable to false, then run:
# Bootstrap only, with uv.sync.enable temporarily set to false:
devenv update # resolve Nix inputs; creates/updates devenv.lock
devenv shell # enter the Nix-provided Python environment
uv lock # generate uv.lock from pyproject.toml
exit
# Restore uv.sync.enable = true and --locked, then verify:
devenv shell
uv lock --check
uv sync --locked
Finally, commit both generated lockfiles with the demo. A team cloning it should not need to repeat the bootstrap or run devenv update; those operations intentionally re-resolve inputs. This is why a blog post containing only configuration snippets cannot itself promise first-clone reproducibility.
uv’s lock is designed to resolve across supported Python versions and platforms, but platform markers, binary wheels, source distributions, libc and native dependencies still decide what can actually install on a given machine. uv’s resolution model and locked sync behavior make that explicit.
Original PyData Global presentation · Published video
4. Add the smallest testable application
# app/main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
def health() -> dict[str, str]:
return {"status": "ok"}
# tests/test_health.py
from fastapi.testclient import TestClient
from app.main import app
def test_health() -> None:
response = TestClient(app).get("/health")
assert response.status_code == 200
assert response.json() == {"status": "ok"}
And a test that actually checks whether the expected database service is available:
# tests/test_database.py
import os
import psycopg
def test_database_connection() -> None:
with psycopg.connect(os.environ["DATABASE_URL"]) as connection:
with connection.cursor() as cursor:
cursor.execute("SELECT 1")
assert cursor.fetchone() == (1,)
This is a connectivity check, not a migration test or a production-grade integration suite. The DB user, socket authentication, readiness, and the psycopg binary wheel must all be checked in the target environment. That distinction matters more than presenting an imagined green test run.
From local shell to CI
Once the lockfiles actually exist, an explicit local workflow might be:
devenv shell
python --version
uv --version
psql --version
uv lock --check
# In another terminal, for the persistent local service:
devenv up -d
# Then, in a configured environment:
devenv tasks run app:lint
devenv tasks run app:test
# Optional: serve the health endpoint from a separate terminal.
devenv tasks run app:serve
# Run the built-in lifecycle (with managed service startup):
devenv test
devenv shell is the lowest-surprise way to opt in. devenv 2.x also offers its native auto-activation hook, so direnv is optional. If the team already uses direnv, its .envrc approval step (direnv allow) makes the trust decision visible. Entering a repository with automatic hooks is still executing project-controlled code; review it first.
Original GIF · Release explanation
For CI, the official devenv GitHub Actions guide uses cachix/install-nix-action, optional Cachix caching, and devenv test. A Linux-only example is:
# .github/workflows/ci.yml — example for a separate demo repo
name: Development environment checks
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v5
- uses: cachix/install-nix-action@v31
- name: Install devenv
run: nix profile add nixpkgs#devenv
- name: Check Python lock
run: devenv shell -- uv lock --check
- name: Exercise environment and tests
run: devenv test
This is an example workflow, not a CI run performed for this article. An ubuntu-24.04 runner controls the broad OS image family, but it still changes over time. nix profile add nixpkgs#devenv also leaves the installed CLI revision floating. For stronger guarantees, pin the action SHAs, image strategy and CLI source/version, then run the workflow. A green devenv test is evidence for the checks it actually ran—not evidence that host kernels or mutable data are identical.
What should two machines compare?
Record the commit, platform, tool versions and lockfile digests before claiming that the second machine reproduced the first:
git rev-parse HEAD
uname -srm
nix --version
devenv version
python --version
uv --version
psql --version
sha256sum devenv.lock uv.lock # Linux; use shasum -a 256 on macOS
uv lock --check
devenv test
Compare the recorded input revisions, not only the first line printed by python --version. Run the same assertions on the same commit; inspect which checks depend on live services or network calls. A mismatch is data to investigate, not something to smooth over by running an update command until it goes away.
Where the promise stops
A declared PostgreSQL service is not a snapshot of PostgreSQL. devenv can initialize a database, but its data directory persists across restarts. Changing initialization SQL is not a migration strategy for an already initialized database. If a test passes only on an old data directory, the definition is not an adequate substitute for isolated fixtures, migrations, or database reset procedures. See PostgreSQL initialization options.
The remaining boundaries are just as important:
- Nix packages versus Python wheels. Nix can pin an interpreter and native libraries; uv resolves Python artifacts. Native ABI compatibility can still fail across platforms.
- Build versus runtime. A controlled build graph does not fix timestamps, randomness, dynamic outside responses, network conditions or local files.
- Reproducibility versus portability. The same locks can describe platform-specific outputs. Linux x86-64 and macOS ARM64 should not be expected to have identical Nix store paths, or universal binary availability.
- Secrets and untracked inputs.
.env, credentials and per-developer overrides must be handled separately. Never write private secrets into a Nix derivation, where they might become part of the store. - Caches versus guarantees. A cache hit avoids a build; a cache miss may require compilation or fail without network access. On multi-user Nix installations, cache configuration and trusted keys require deliberate administration. Adding an ordinary developer to
trusted-userscan confer very broad privilege; do not do it casually. Nix security options. - Development versus deployment. A working
devenv shelldoes not reproduce production storage, network configuration or secrets. devenv’s OCI container outputs can help bridge packaging; its Machines capabilities were introduced as experimental and are not a default production contract.
The useful response is to measure the boundary: isolate test databases, pin what is meaningful, audit the rest, and make the checks executable. Declaring more configuration is not an end in itself.
What this costs—and when not to use it
Nix and devenv add another configuration language, a Nix installation, input updates, store maintenance, and an initial evaluation/download path. They can make cross-language toolchains easier to share, but contributors must be comfortable debugging the Nix layer and the Python layer. On systems with limited cache coverage, the first setup can be expensive; no performance number is meaningful without the host, cache and measurement method.
There are sensible smaller choices. For a pure Python library, uv alone may be enough. For a short Nix-only toolchain, nix develop can avoid another abstraction. Docker Compose or Dev Containers may be more natural when the team needs a container boundary and container-oriented workflows. mise concentrates on tools and tasks; Pixi is attractive for Conda/PyPI environments. None of those alternatives makes persistent database state magically reproducible, either. The best choice depends on which layer is currently drifting.
The practical decision rule is simple: choose Nix + devenv when the project consistently spans system tools + language runtime + native libraries + local services + shared checks, and when the team will maintain its pins. Otherwise, resist paying for more machinery than the problem requires.
A more precise definition of done
A development environment is meaningfully reproducible when you can point to a specific revision, re-create its declared inputs on a supported platform, run the same checks in an isolated context, and explain every relevant dependency still outside that process. That is more useful—and more defensible—than “works on my machine.”