Desarrollo reproducible con Nix y devenv

Persona programando de noche ante varias pantallas
Fotografía de Abdullahi Mohamud · Unsplash (licencia gratuita). Entorno de desarrollo y herramientas; no sesión Nix real. · Ver imagen original

Dos desarrolladores clonan el mismo repositorio. Ambos siguen su README. Uno ejecuta Python 3.13 contra PostgreSQL 17; el otro tiene Python 3.12, un libpq diferente y una base de datos sobrante de la rama de la semana pasada. La aplicación se inicia en ambas máquinas, pero sólo una pasa las pruebas.

Aquí no existe un único “problema de dependencia”. Los paquetes de Python, el intérprete, las bibliotecas nativas, el servidor de base de datos, el contenido de la base de datos y los comandos de prueba son fuentes independientes de variación. Un administrador de paquetes puede eliminar algunos de ellos y dejar otros intactos.

La pregunta útil no es si un entorno es reproducible. Se trata de qué entradas se controlan, cuáles aún son mutables y cómo otra máquina demuestra que recibió el entorno previsto. Esta es la lente a través de la cual Nix y devenv se vuelven interesantes.

La portada es una fotografía externa acreditada que se utiliza como referencia visual, no una captura de pantalla de Nix o Devenv. La ilustración de la portada técnica original aparece a continuación en el artículo, junto con demostraciones previas publicadas y una grabación de la conferencia: referencias para inspeccionar, no resultados del ejemplo de este artículo.

Separación de las dependencias fijadas de Nix y Python frente al estado mutable de los datos y secretos.
Diagrama original. Las dependencias fijadas no garantizan el mismo estado de ejecución ni resultados idénticos byte a byte.

La reproducibilidad tiene más de un límite.

“Reproducible” a menudo comprime varias afirmaciones distintas:

  • Resolución de dependencia: las mismas entradas de paquete declaradas se resuelven en las versiones y artefactos previstos.
  • Entorno de compilación: se controlan el compilador, el intérprete, las bibliotecas del sistema y las entradas de compilación relevantes.
  • Comportamiento en tiempo de ejecución: la aplicación ve la configuración, los servicios, los relojes, el estado del sistema de archivos y los sistemas externos equivalentes.
  • Resultado de la compilación: dos compilaciones independientes producen bytes idénticos. Esta es una afirmación más sólida que obtener versiones de paquetes coincidentes.

Un pip install exitoso, o incluso un archivo de bloqueo de Python confirmado, no establece ninguno de estos de forma aislada. Nix tampoco garantiza automáticamente la salida bit por bit: las marcas de tiempo no deterministas o los pasos de compilación pueden sobrevivir a un gráfico de dependencia bien especificado. El sandbox de Nix reduce el acceso accidental a las entradas del host, pero no convierte el software arbitrario en software determinista. Consulte el Nix manual on build isolation.

Ilustración conceptual de entornos reproducibles con Nix y devenv: flake, dependencias y servicios.
Ilustración técnica original del entorno reproducible; no es una captura ni el resultado de una prueba.

Nix es la base, no todo el flujo de trabajo

Nix proporciona un administrador de paquetes y un modelo de compilación creado en torno a las entradas declaradas y /nix/store. Una derivación describe cómo se debe construir un resultado; Las rutas de almacenamiento permiten que coexistan múltiples versiones y variantes de dependencia sin reemplazar una sola instalación en todo el sistema. nixpkgs es una colección de paquetes, no un sinónimo de Nix o NixOS. NixOS es un sistema operativo independiente construido sobre maquinaria relacionada.

Es importante fijar una revisión de nixpkgs. Solicitar la rama nixpkgs-unstable en movimiento dos veces, con meses de diferencia, puede resolver diferentes confirmaciones. Un archivo de bloqueo registra la revisión resuelta para que un compañero de equipo pueda intentar usar ese gráfico de entrada en lugar de lo que la rama apunte hoy. Las cachés binarias pueden proporcionar objetos de tienda prediseñados para ese gráfico en lugar de compilar todo localmente; son un mecanismo de aceleración y distribución, no una prueba de equivalencia de tiempo de ejecución. Nix’s substituter documentation explica el modelo de confianza.

Un shell nix develop simple puede ser todo lo que necesita un proyecto pequeño. También puede utilizar Nix Flakes, cuyos pines flake.lock escaman las entradas. Los copos no son un requisito previo para usar Nix, y flake.lock no es el archivo de bloqueo utilizado por un proyecto devenv normal. devenv tiene su propio modelo de entrada y devenv.lock; se ubica por encima de Nix en lugar de reemplazarlo. Consulte devenv inputs y Nix flakes.

Lo que agrega devenv

Una vez que un proyecto necesita más que un compilador o intérprete, el shell de desarrollo se convierte en una pequeña plataforma local. devenv le brinda a esa plataforma un modelo explícito: paquetes, integraciones de lenguajes, variables de entorno, procesos, definiciones de servicios, tareas, pruebas y enlaces de ciclo de vida. En devenv 2.x, su administrador de procesos nativo Rust es el predeterminado; Los tutoriales más antiguos de process-compose no deben copiarse sin verificar 2.0 migration guide.

Grabación oficial de la interfaz de terminal de devenv 2.0 con evaluaciones y tareas.
Grabación oficial de devenv 2.0, marzo de 2026 (Domen Kožar / devenv). No corresponde al ejemplo de este artículo.

Original GIF · Release explanation

La división de responsabilidades es concreta:

ArchivoResponsabilidadLo que no fija
devenv.nixHerramientas de proyecto, idiomas, servicios, tareas, comprobaciones.Las revisiones de todas las entradas por sí solas.
devenv.yamlReferencias de entrada, importaciones, regla de compatibilidad CLILa entrada resuelta se confirma por sí sola
devenv.lockEntradas devenv/Nix resueltasDependencias de PyPI o filas de bases de datos
pyproject.tomlMetadatos del proyecto Python y restricciones de dependencia.Un entorno Python exactamente resuelto por sí solo
uv.lockResolución de dependencia de Python y artefactosDatos de PostgreSQL, kernel de host o secretos

devenv update actualiza deliberadamente el gráfico de entrada de Nix. Esa es una operación de mantenimiento, no algo que deba ejecutarse implícitamente en una compilación de CI supuestamente congelada. devenv’s file reference describe los respectivos archivos de configuración.

Un pequeño servicio con dos archivos de bloqueo.

Considere un punto final de salud FastAPI respaldado por un servicio PostgreSQL local, con Ruff y Pytest para realizar comprobaciones. La demostración es intencionalmente pequeña: su propósito es exponer los límites en lugar de comparar un marco.

Estado de verificación: la configuración siguiente combina características documentadas de devenv 2.x y uv, pero la combinación completa no se ha ejecutado para este artículo. Trátelo como un candidato de implementación, no como una plantilla medida o certificada de compatibilidad. En particular, la conexión de la base de datos y la preparación del proceso deben confirmarse en un host Nix real.

El diseño previsto del repositorio es:

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. Declarar las entradas Nix

devenv.yaml comienza con una referencia que se resolverá en 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"

La URL anterior es una rama en movimiento hasta devenv.lock registra una resolución. La regla de versión verifica la compatibilidad; no soluciona qué binario devenv CLI instala un desarrollador. Para obtener una demostración completamente validada, registre y aplique la versión CLI exacta que realmente se probó. No inventes un devenv.lock manualmente: debe ser generado por devenv y comprometido con el proyecto.

2. Describir el shell, el servicio y los controles.

El siguiente devenv.nix propone un único intérprete de Python proporcionado por Nix, uv para dependencias de Python, PostgreSQL como servicio local y tareas con nombre:

# 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
  '';
}
Grabación oficial del gestor de procesos nativo de devenv 2.0 supervisando servicios.
Demostración oficial del gestor de procesos de devenv 2.0; no demuestra que se ejecutase el ejemplo de Python y PostgreSQL.

Original GIF · Release explanation

El Python integration documenta tanto la sincronización uv como la dependencia de devenv:python:uv para las tareas: devenv tasks run no ejecuta automáticamente todas las tareas de entrada del shell. El PostgreSQL module documenta el initialDatabases y el test lifecycle inicia los procesos habilitados antes de las pruebas. Si se puede acceder al socket PostgreSQL cuando se intenta la primera conexión es una afirmación práctica de preparación para probar, no un resultado que asumir.

Hay una razón sutil de seguridad y corrección para mantener el DATABASE_URL local en el servicio: abrir PostgreSQL en todas las interfaces solo para facilitar la demostración introduce una superficie de ataque no relacionada. Una contraseña secreta de base de datos, si la implementación la necesita, pertenece a un proveedor secreto de tiempo de ejecución, no a la expresión Nix ni al almacén. devenv’s secrets guidance cubre esa distinción.

3. Bloquee el gráfico de Python por separado

Para pyproject.toml, declare las dependencias sin pretender que un rango de versiones sea un bloqueo completo:

[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"]

El primer arranque tiene una restricción de orden inevitable: la configuración registrada anterior exige uv.lock antes de que comience la sincronización automática. Para generar los bloqueos para una nueva demostración, cambie temporalmente languages.python.uv.sync.enable a false, luego ejecute:

# 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

Finalmente, confirme ambos archivos de bloqueo generados con la demostración. Un equipo que clona no debería necesitar repetir el arranque ni ejecutar devenv update; esas operaciones vuelven a resolver intencionalmente las entradas. Esta es la razón por la que una publicación de blog que contenga solo fragmentos de configuración no puede prometer por sí misma reproducibilidad en el primer clon.

El bloqueo de uv está diseñado para resolverse entre versiones y plataformas de Python compatibles, pero los marcadores de plataforma, las ruedas binarias, las distribuciones de código fuente, libc y las dependencias nativas aún deciden qué se puede instalar realmente en una máquina determinada. uv’s resolution model y locked sync behavior lo hacen explícito.

Demostración de Avik Basu en PyData Global 2024, ejemplo histórico de Nix y Python, no validación del artículo con devenv 2.x.

Original PyData Global presentation · Published video

4. Agregue la aplicación comprobable más pequeña

# 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"}

Y una prueba que realmente verifica si el servicio de base de datos esperado está disponible:

# 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,)

Esta es una verificación de conectividad, no una prueba de migración ni una suite de integración de nivel de producción. El usuario de la base de datos, la autenticación del socket, la preparación y la rueda binaria psycopg deben verificarse en el entorno de destino. Esa distinción importa más que presentar una prueba ecológica imaginada.

Del shell local al CI

Una vez que los archivos de bloqueo realmente existen, un flujo de trabajo local explícito podría ser:

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 es la forma más sencilla de participar. devenv 2.x también ofrece su auto-activation hook nativo, por lo que direnv es opcional. Si el equipo ya utiliza direnv, su paso de aprobación .envrc (direnv allow) hace visible la decisión de confianza. Ingresar a un repositorio con enlaces automáticos sigue ejecutando código controlado por el proyecto; revíselo primero.

Grabación oficial de devenv 2.0 recompilando la shell en segundo plano y recargándola tras cambiar la configuración.
Demostración oficial de recarga de la shell de devenv, marzo de 2026. El comportamiento puede variar con otras versiones de la CLI.

Original GIF · Release explanation

Para CI, official devenv GitHub Actions guide utiliza cachix/install-nix-action, almacenamiento en caché Cachix opcional y devenv test. Un ejemplo exclusivo de Linux es:

# .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

Este es un flujo de trabajo de ejemplo, no una ejecución de CI realizada para este artículo. Un ejecutor ubuntu-24.04 controla la amplia familia de imágenes del sistema operativo, pero aún cambia con el tiempo. nix profile add nixpkgs#devenv también deja flotante la revisión CLI instalada. Para obtener garantías más sólidas, fije los SHA de acción, la estrategia de imagen y la fuente/versión de CLI, luego ejecute el flujo de trabajo. Un devenv test verde es evidencia de las comprobaciones que realmente ejecutó, no evidencia de que los núcleos del host o los datos mutables sean idénticos.

¿Qué deberían comparar dos máquinas?

Registre la confirmación, la plataforma, las versiones de la herramienta y los resúmenes del archivo de bloqueo antes de afirmar que la segunda máquina reprodujo la primera:

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 las revisiones de entrada registradas, no solo la primera línea impresa por python --version. Ejecute las mismas afirmaciones en la misma confirmación; Inspeccione qué controles dependen de servicios en vivo o llamadas de red. Una discrepancia son datos que hay que investigar, no algo que se debe solucionar ejecutando un comando de actualización hasta que desaparezca.

donde termina la promesa

Un servicio PostgreSQL declarado no es una instantánea de PostgreSQL. devenv puede inicializar una base de datos, pero su directorio de datos persiste después de los reinicios. Cambiar el SQL de inicialización no es una estrategia de migración para una base de datos ya inicializada. Si una prueba pasa solo en un directorio de datos antiguo, la definición no es un sustituto adecuado para dispositivos aislados, migraciones o procedimientos de restablecimiento de bases de datos. Ver PostgreSQL initialization options.

Los límites restantes son igualmente importantes:

  • Paquetes Nix versus ruedas de Python. Nix puede anclar un intérprete y bibliotecas nativas; uv resuelve los artefactos de Python. La compatibilidad nativa de ABI aún puede fallar en todas las plataformas.
  • Construcción versus tiempo de ejecución. Un gráfico de compilación controlado no corrige marcas de tiempo, aleatoriedad, respuestas dinámicas externas, condiciones de red o archivos locales.
  • Reproducibilidad versus portabilidad. Los mismos candados pueden describir resultados específicos de la plataforma. No se debe esperar que Linux x86-64 y macOS ARM64 tengan rutas de almacenamiento Nix idénticas o disponibilidad binaria universal.
  • Secretos y entradas sin seguimiento. .env, las credenciales y las anulaciones por desarrollador se deben manejar por separado. Nunca escriba secretos privados en una derivación de Nix, donde podrían convertirse en parte de la tienda.
  • Cachés frente a garantías. Un acierto en el caché evita una compilación; una pérdida de caché puede requerir compilación o fallar sin acceso a la red. En instalaciones Nix multiusuario, la configuración de la caché y las claves confiables requieren una administración deliberada. Agregar un desarrollador normal a trusted-users puede conferir privilegios muy amplios; no lo hagas casualmente. Nix security options.
  • Desarrollo versus implementación. Un devenv shell funcional no reproduce el almacenamiento de producción, la configuración de red ni los secretos. OCI container outputs de devenv puede ayudar a unir el embalaje; sus capacidades Machines se introdujeron como experimentales y no son un contrato de producción predeterminado.

La respuesta útil es medir el límite: aislar las bases de datos de prueba, fijar lo que es significativo, auditar el resto y hacer que las comprobaciones sean ejecutables. Declarar más configuración no es un fin en sí mismo.

Cuánto cuesta y cuándo no usarlo

Nix y devenv agregan otro lenguaje de configuración, una instalación de Nix, actualizaciones de entrada, mantenimiento de la tienda y una ruta de evaluación/descarga inicial. Pueden hacer que las cadenas de herramientas en varios idiomas sean más fáciles de compartir, pero los contribuyentes deben sentirse cómodos depurando la capa Nix y la capa Python. En sistemas con cobertura de caché limitada, la primera configuración puede resultar costosa; ningún número de rendimiento tiene significado sin el host, el caché y el método de medición.

Hay opciones más pequeñas y sensatas. Para una biblioteca Python pura, solo uv puede ser suficiente. Para una cadena de herramientas corta exclusiva de Nix, nix develop puede evitar otra abstracción. Docker Compose o Dev Containers pueden ser más naturales cuando el equipo necesita un límite de contenedor y flujos de trabajo orientados a contenedores. mise se concentra en herramientas y tareas; Pixi es atractivo para entornos Conda/PyPI. Ninguna de esas alternativas hace que el estado persistente de la base de datos sea mágicamente reproducible. La mejor elección depende de qué capa se está desplazando actualmente.

La regla de decisión práctica es simple: elija Nix + devenv cuando el proyecto abarque consistentemente herramientas del sistema + tiempo de ejecución del lenguaje + bibliotecas nativas + servicios locales + comprobaciones compartidas, y cuando el equipo mantendrá sus pines. De lo contrario, resista pagar por más maquinaria de la que requiere el problema.

Una definición más precisa de hecho

Un entorno de desarrollo es significativamente reproducible cuando puede señalar una revisión específica, recrear sus entradas declaradas en una plataforma compatible, ejecutar las mismas comprobaciones en un contexto aislado y explicar cada dependencia relevante que aún está fuera de ese proceso. Esto es más útil (y más defendible) que “funciona en mi máquina”.