Créer des environnements de développement reproductibles avec Nix

Un fichier shell.nix à la racine de votre projet, un nix-shell (ou nix develop), et tout votre outillage est là — même version, même configuration, pour tous les membres de l’équipe. Pas de README à re-lire, pas de conflits de versions, pas de “ça marche sur ma machine”. Ce guide vous montre comment construire ces environnements pour Python, Node.js, Rust et des projets mixtes.

Ce que vous allez apprendre

• Comprendre le rôle de mkShell et la structure d’un shell.nix
• Créer un environnement Python avec bibliothèques via withPackages
• Créer un environnement Node.js et un environnement Rust
• Passer des variables d’environnement et un shellHook au shell
• Utiliser nix develop avec un flake comme alternative moderne
• Charger l’environnement automatiquement avec direnv
• Comparer nix-shell / nix develop avec venv, nvm et Docker

Dans quel contexte ?

Chaque projet a ses dépendances : une version de Python, des bibliothèques, des outils CLI, une version de Node.js… Au quotidien, vous rencontrez ces situations :

• un nouveau développeur rejoint le projet et passe une demi-journée à installer les bons outils,
• deux projets exigent des versions différentes de Node.js ou Python,
• un script CI échoue parce que la version de jq diffère du poste local,
• le README dit “installer gcc, cmake, libssl-dev, python3.12…” mais personne ne le maintient à jour.

Avec Nix, un seul fichier (shell.nix ou flake.nix) décrit l’environnement de manière reproductible. Il est versionné avec le code et garantit que tout le monde travaille avec le même outillage.

mkShell : la brique fondamentale

pkgs.mkShell est une fonction qui crée un environnement de développement. Elle attend un attrset avec :

Attribut	Rôle
packages	Liste des paquets disponibles dans le shell
shellHook	Script exécuté à l’entrée dans le shell
name	Nom affiché (optionnel)
toute autre clé	Devient une variable d’environnement

Glissez pour voir

Premier shell.nix minimal

shell.nix

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  packages = with pkgs; [
    python312
    git
    vim
  ];
}

Pour entrer dans l’environnement :

nix-shell

Résultat

Python 3.12.13
git version 2.53.0

Quand vous tapez exit, les outils disparaissent — ils ne sont accessibles que dans le shell Nix.

Astuce

Utilisez nix-shell --run "commande" pour exécuter une seule commande sans entrer dans le shell interactif. Pratique en CI.

Environnement Python avec bibliothèques

Python “nu” ne suffit pas : vous avez besoin de requests, flask, pytest… La fonction withPackages crée un Python qui inclut les bibliothèques demandées.

shell.nix

{ pkgs ? import <nixpkgs> {} }:

let
  pythonEnv = pkgs.python312.withPackages (ps: [
    ps.requests
    ps.flask
    ps.pytest
  ]);
in
pkgs.mkShell {
  packages = with pkgs; [
    pythonEnv
    git
    ripgrep
  ];

  PROJECT_NAME = "demo-api";
  FLASK_DEBUG = "1";

  shellHook = ''
    echo "=================================="
    echo " Projet: $PROJECT_NAME"
    echo " Python: $(python3 --version 2>&1)"
    echo " Flask debug: $FLASK_DEBUG"
    echo "=================================="
  '';
}

nix-shell

Résultat

==================================
 Projet: demo-api
 Python: Python 3.12.13
 Flask debug: 1
==================================

Vérifions que les bibliothèques sont bien disponibles :

python3 -c "import requests; print(f'requests {requests.__version__}')"
python3 -c "import pytest; print(f'pytest {pytest.__version__}')"

Résultat

requests 2.32.5
pytest 9.0.2

Les bibliothèques sont installées dans le store Nix, pas dans un venv classique. Elles disparaissent quand vous quittez le shell.

Comprendre withPackages

withPackages attend une fonction qui reçoit l’ensemble des paquets Python disponibles (ps) et retourne la liste de ceux que vous voulez :

pkgs.python312.withPackages (ps: [
  ps.requests    # ← sélectionne requests dans l'ensemble Python
  ps.flask       # ← sélectionne flask
])

La syntaxe ps: [ ... ] est une fonction anonyme (lambda) — un concept couvert dans le guide du langage Nix.

Trouver les noms de paquets Python

Tous les paquets Python nixpkgs sont listés avec le préfixe python3Packages. :

nix search nixpkgs python3Packages.requests

Dans un shell.nix, on utilise ps.requests (raccourci fourni par withPackages).

Environnement Node.js

shell.nix

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  packages = with pkgs; [
    nodejs_22
    jq
    curl
  ];

  shellHook = "echo 'Node.js:' $(node --version)";
}

nix-shell --run "node --version && jq --version"

Résultat

v22.22.2
jq-1.8.1

Note

Nix gère la version exacte de Node.js. Plus besoin de nvm ou fnm pour jongler entre versions par projet.

Environnement Rust

shell.nix

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  packages = with pkgs; [
    rustc
    cargo
    gcc
  ];

  RUST_BACKTRACE = "1";

  shellHook = "echo 'Rust:' $(rustc --version)";
}

nix-shell --run "rustc --version && cargo --version"

Résultat

rustc 1.94.0 (4a4ef493e 2026-03-02)
cargo 1.94.0 (85eff7c80 2026-01-15)

La variable RUST_BACKTRACE = "1" est automatiquement exportée — toute clé inconnue de mkShell devient une variable d’environnement.

Variables d’environnement et shellHook

Variables d’environnement

Ajoutez simplement des clés à l’attrset de mkShell :

pkgs.mkShell {
  packages = [ ... ];

  # Deviennent des variables d'environnement
  PROJECT_NAME = "mon-api";
  FLASK_DEBUG = "1";
  FLASK_RUN_PORT = "5000";
  DATABASE_URL = "postgresql://localhost:5432/dev";
}

nix-shell --run "echo \$PROJECT_NAME \$FLASK_RUN_PORT"

Résultat

mon-api 5000

shellHook : script d’initialisation

Le shellHook s’exécute à chaque entrée dans le shell. Il sert à :

• afficher un message de bienvenue,
• activer un environnement,
• vérifier des prérequis,
• créer des fichiers temporaires.

shellHook = ''
  echo "=================================="
  echo " Projet: $PROJECT_NAME"
  echo " Python: $(python3 --version 2>&1)"
  echo "=================================="
'';

Attention

Les chaînes multilignes Nix utilisent '' (deux apostrophes simples). L’indentation minimale commune est automatiquement supprimée.

nix develop : l’alternative moderne avec les flakes

nix develop est l’équivalent de nix-shell dans le monde des flakes. Il nécessite un fichier flake.nix (et un dépôt Git).

flake.nix

{
  description = "Environnement de développement Node.js";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  };

  outputs = { self, nixpkgs }:
  let
    system = "x86_64-linux";
    pkgs = nixpkgs.legacyPackages.${system};
  in {
    devShells.${system}.default = pkgs.mkShell {
      packages = with pkgs; [
        nodejs_22
        jq
        curl
      ];

      shellHook = "echo 'Node.js:' $(node --version)";
    };
  };
}

1. Initialisez le dépôt (les flakes exigent Git) :

   git init && git add flake.nix

2. Entrez dans l’environnement :

   nix develop

   Résultat

   Node.js: v22.22.2

3. Vérifiez le flake.lock généré :

   cat flake.lock | head -10

   Extrait de flake.lock

   {
     "nodes": {
       "nixpkgs": {
         "locked": {
           "lastModified": 1775710090,
           "narHash": "sha256-ar3rofg+awPB8QXDaFJhJ2jJhu+...",
           "rev": "4c1018dae018162ec878d42fec712642d214fdfa",

Le flake.lock fige automatiquement la version de nixpkgs. C’est le principal avantage sur shell.nix classique.

nix-shell vs nix develop : quand utiliser lequel ?

Critère	nix-shell + shell.nix	nix develop + flake.nix
Verrouillage	Manuel (fetchTarball + sha256)	Automatique (flake.lock)
Prérequis	Aucun	Dépôt Git obligatoire
Reproductibilité	Bonne si pinné	Garantie par le lock
Simplicité	Plus simple à démarrer	Plus verbeux au début
Recommandation	Projets simples, scripts	Projets d’équipe, CI

Glissez pour voir

Astuce

Pour un projet personnel rapide, shell.nix suffit. Pour un projet d’équipe ou de CI, préférez flake.nix avec nix develop.

Modulariser son environnement

Quand le shell.nix grandit, séparez la configuration dans des fichiers dédiés.

Structure du projet

mon-projet/
├── shell.nix         # point d'entrée
├── config.nix        # variables du projet
└── python-env.nix    # environnement Python

config.nix — les variables

config.nix

{
  projectName = "demo-api";
  projectVersion = "1.0.0";
  debugMode = true;
  flaskPort = 5000;
}

python-env.nix — l’environnement Python

python-env.nix

{ pkgs }:

pkgs.python312.withPackages (ps: [
  ps.requests
  ps.flask
  ps.pytest
])

Ce fichier est une fonction qui attend pkgs en argument.

shell.nix — assemblage

shell.nix

{ pkgs ? import <nixpkgs> {} }:

let
  config = import ./config.nix;
  pythonEnv = import ./python-env.nix { inherit pkgs; };

  debugTools = if config.debugMode then with pkgs; [
    htop
    ncdu
  ] else [];
in
pkgs.mkShell {
  name = "${config.projectName}-dev";

  packages = with pkgs; [
    pythonEnv
    git
    ripgrep
  ] ++ debugTools;

  PROJECT_NAME = config.projectName;
  PROJECT_VERSION = config.projectVersion;
  FLASK_RUN_PORT = toString config.flaskPort;

  shellHook = ''
    echo "Projet: ${config.projectName} v${config.projectVersion}"
    echo "Debug: ${if config.debugMode then "ON" else "OFF"}"
  '';
}

nix-shell --run "echo \$PROJECT_NAME \$PROJECT_VERSION \$FLASK_RUN_PORT && which htop"

Résultat

Projet: demo-api v1.0.0
Debug: ON
demo-api 1.0.0 5000
/nix/store/zalk6ygj90a1d1jyk6rn4ha22fh19gzd-htop-3.4.1/bin/htop

inherit pkgs est un raccourci pour pkgs = pkgs — il transmet la variable du même nom. La modularisation est plus approfondie dans le guide sur l’import, la factorisation et le pinning.

Charger l’environnement automatiquement avec direnv

direnv charge automatiquement l’environnement Nix quand vous entrez dans le dossier du projet. Plus besoin de taper nix-shell manuellement.

1. Installez direnv et nix-direnv :

   nix profile add nixpkgs#direnv nixpkgs#nix-direnv

2. Activez le hook shell (ajoutez à ~/.bashrc ou ~/.zshrc) :

   eval "$(direnv hook bash)"   # ou zsh

3. Créez .envrc à la racine du projet :

   .envrc

   use nix

   Ou pour les flakes :

   .envrc

   use flake

4. Autorisez le répertoire :

   direnv allow

Désormais, chaque cd mon-projet/ charge automatiquement l’environnement Nix, et cd .. le décharge. Les outils apparaissent et disparaissent sans intervention.

Note

nix-direnv met en cache l’environnement pour éviter une réévaluation à chaque cd. Le rechargement n’a lieu que quand shell.nix ou flake.nix change.

L’isolation en pratique

Hors du shell Nix, seul le Python système (Debian) est disponible. Dans le shell, Nix fournit ses propres versions — tout est isolé :

Démonstration d'isolation

=== HORS nix-shell ===
htop: introuvable
Python 3.11.2                ← Python Debian

=== DANS nix-shell ===
/nix/store/.../bin/htop      ← htop Nix
Python 3.12.13               ← Python Nix

=== APRÈS nix-shell ===
htop: disparu                ← retour à l'état initial

Chaque projet peut avoir sa propre version de Python, Node.js ou Rust sans conflits. Plus besoin de pyenv, nvm, rustup pour gérer les versions par projet.

Comparer avec venv, nvm et Docker

Critère	venv / nvm	Docker	Nix (shell.nix / flake.nix)
Portée	Un seul langage	Système complet	Tous les outils
Overhead	Aucun	Conteneur (RAM, disque)	Aucun (accès direct)
Reproductibilité	requirements.txt / .nvmrc	Dockerfile	shell.nix / flake.lock
Isolation	Bibliothèques uniquement	Totale (FS, réseau…)	Binaires et bibliothèques
CI	pip install + nvm use	docker run	nix-shell —run
Partage	Fichier texte	Image (Docker Hub)	Fichier Nix versionné

Glissez pour voir

• venv / nvm : limités à un seul langage ; Nix gère tout.
• Docker : isolation totale mais plus lourd ; Nix n’ajoute pas de couche.
• Nix : le meilleur compromis pour les environnements de développement.

Astuce

Nix et Docker ne s’excluent pas. Utilisez Nix pour le développement local et Docker pour le déploiement en production.

Dépannage courant

Symptôme	Cause probable	Solution
nix-shell ne trouve pas un paquet	Nom incorrect	nix search nixpkgs <nom> pour trouver le bon nom
import <nixpkgs> échoue	Pas de channel configuré	nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs && nix-channel --update
Python ne voit pas les bibliothèques	withPackages manquant	Utiliser python312.withPackages (ps: [ ps.xxx ])
Changements dans shell.nix non pris en compte	Cache direnv	direnv reload ou quitter et relancer nix-shell
nix develop échoue	Pas de dépôt Git	git init && git add flake.nix
shellHook ne s’exécute pas	Syntaxe Nix incorrecte	Vérifier les '' (multilignes) et les ${} (interpolation)

Glissez pour voir

À retenir

• Un fichier shell.nix ou flake.nix à la racine du projet décrit l’environnement complet : langages, outils CLI, variables d’environnement.
• pkgs.mkShell est la fonction centrale — elle prend une liste de paquets, un shellHook et des variables d’environnement.
• python312.withPackages crée un Python avec ses bibliothèques, sans pip install.
• Toute clé inconnue de mkShell devient une variable d’environnement exportée.
• nix develop (flakes) ajoute le verrouillage automatique des versions — privilégiez-le pour les projets d’équipe.
• direnv charge l’environnement automatiquement au cd — c’est le confort ultime au quotidien.
• Les outils n’existent que dans le shell Nix — l’isolation est totale.

Prochaines étapes

Import, factorisation et pinning Modularisez vos fichiers Nix et figez les versions pour la reproductibilité.

Les flakes Le workflow moderne avec verrouillage automatique des dépendances.

Le langage Nix Revenez aux fondamentaux si une syntaxe vous échappe dans un shell.nix.

×

📖 Voir la documentation →