Comprendre et utiliser les flakes Nix

Les flakes sont le mécanisme de reproductibilité native de Nix. Un fichier flake.nix déclare des dépendances versionnées (les inputs), et flake.lock verrouille leurs révisions exactes. Résultat : chaque membre de l’équipe, chaque serveur CI et chaque machine de production obtient exactement le même environnement. Ce guide couvre la structure complète d’un flake, les commandes de gestion, et la migration depuis shell.nix.

Ce que vous allez apprendre

• Créer un flake avec nix flake init et comprendre sa structure
• Déclarer des inputs (nixpkgs, flake-utils) et les verrouiller avec flake.lock
• Définir des outputs : devShells, packages, apps
• Construire, exécuter et inspecter un flake
• Convertir un projet shell.nix classique vers les flakes
• Supporter plusieurs architectures avec flake-utils

Dans quel contexte ?

Les channels Nix classiques (guide précédent) posent un problème fondamental : chaque machine peut pointer vers une révision différente de nixpkgs. Même avec fetchTarball et un hash, le pinning reste manuel et fragile.

Les flakes résolvent ce problème en pratique quotidienne :

• Votre collègue clone votre dépôt et obtient les mêmes versions de Python, Node.js et tous les outils — automatiquement
• La CI construit avec les mêmes dépendances que votre poste — sans configuration supplémentaire
• Vous mettez à jour nixpkgs d’un seul nix flake update, avec un diff vérifiable dans flake.lock
• Vous composez plusieurs sources (nixpkgs stable, un overlay privé, un outil depuis GitHub) dans un seul fichier déclaratif

Activer les flakes dans votre configuration Nix

Les flakes sont une fonctionnalité expérimentale qu’il faut activer explicitement. Si vous avez suivi le guide d’installation, c’est déjà fait.

Vérifiez votre configuration :

grep experimental-features ~/.config/nix/nix.conf 2>/dev/null || \
grep experimental-features /etc/nix/nix.conf 2>/dev/null

experimental-features = nix-command flakes

Si la ligne est absente :

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Expérimental ne signifie pas instable

Le mot « expérimental » dans Nix signifie que l’interface peut encore évoluer, pas que la fonctionnalité est fragile. Les flakes sont utilisés en production par la majorité de l’écosystème Nix depuis plusieurs années.

Initialiser un flake avec nix flake init

La commande nix flake init génère un flake.nix de base dans le répertoire courant. Le répertoire doit être un dépôt Git — les flakes ne fonctionnent qu’avec des fichiers suivis par Git.

1. Créez un répertoire et initialisez Git :

   mkdir mon-projet && cd mon-projet
   git init

2. Générez le flake de base :

   nix flake init

   wrote: "/home/lab/mon-projet/flake.nix"

3. Examinez le fichier généré :

   cat flake.nix

   {
     description = "A very basic flake";
   
     inputs = {
       nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
     };
   
     outputs = { self, nixpkgs }: {
   
       packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
   
       packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
   
     };
   }

4. Ajoutez le fichier à Git (obligatoire pour que Nix le voie) :

   git add flake.nix

Templates disponibles

nix flake init utilise le template par défaut. Vous pouvez lister les templates officiels avec nix flake show templates — il en existe pour Python, Go, Haskell, Rust, LaTeX et bien d’autres.

Anatomie du fichier flake.nix

Un flake.nix est une expression Nix qui retourne un attribute set avec trois clés :

{
  description = "Description du projet";   # texte libre

  inputs = {
    # Les dépendances et leur source
  };

  outputs = { self, ... }:
    # Ce que le flake produit
    { };
}

Clé	Rôle	Obligatoire
description	Texte affiché par nix flake metadata	Non (recommandé)
inputs	Dépendances externes avec leur URL	Oui
outputs	Fonction qui retourne packages, shells, apps…	Oui

Glissez pour voir

La clé outputs est une fonction dont le premier argument est toujours self (le flake lui-même), suivi d’un argument par input déclaré.

Déclarer ses dépendances dans inputs

Les inputs déclarent les sources dont votre flake dépend. La plus courante est nixpkgs.

Types de sources

GitHub

inputs = {
  # Branche spécifique
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

  # Branche stable
  nixpkgs-stable.url = "github:nixos/nixpkgs/nixos-24.11";

  # Un outil tiers
  flake-utils.url = "github:numtide/flake-utils";
};

Format : github:propriétaire/dépôt/branche

Git générique

inputs = {
  mon-outil.url = "git+https://gitlab.example.com/equipe/outil.git?ref=main";
};

Format : git+URL?ref=branche

Chemin local

inputs = {
  mon-lib.url = "path:./lib";
};

Utile pour un monorepo contenant plusieurs flakes.

Archive

inputs = {
  source.url = "https://example.com/archive.tar.gz";
  source.flake = false;
};

flake = false indique que la source n’est pas elle-même un flake.

Partager un même nixpkgs entre inputs avec follows

Quand un input (comme flake-utils) dépend lui-même de nixpkgs, vous pouvez forcer l’utilisation de votre version :

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  flake-utils.url = "github:numtide/flake-utils";

  # Force flake-utils à utiliser notre nixpkgs
  flake-utils.inputs.systems.follows = "systems";
  systems.url = "github:nix-systems/x86_64-linux";
};

Sans follows, chaque input télécharge sa propre copie de ses dépendances. Avec follows, vous déduplicez et garantissez la cohérence.

Le fichier flake.lock : reproductibilité garantie

La première évaluation d’un flake génère automatiquement un flake.lock. Ce fichier JSON enregistre la révision exacte de chaque input :

{
  "nodes": {
    "nixpkgs": {
      "locked": {
        "lastModified": 1775710090,
        "narHash": "sha256-ar3rofg+awPB8QXDaFJhJ2jJhu+KqN/PRCXeyuXR76E=",
        "owner": "nixos",
        "repo": "nixpkgs",
        "rev": "4c1018dae018162ec878d42fec712642d214fdfa",
        "type": "github"
      },
      "original": {
        "owner": "nixos",
        "ref": "nixos-unstable",
        "repo": "nixpkgs",
        "type": "github"
      }
    },
    "root": {
      "inputs": {
        "nixpkgs": "nixpkgs"
      }
    }
  },
  "root": "root",
  "version": 7
}

Trois informations clés :

• rev : le commit exact de nixpkgs utilisé
• narHash : le hash cryptographique du contenu — garantit l’intégrité
• original : la source telle que déclarée dans inputs

Committer flake.lock

Le fichier flake.lock doit être commité dans Git. C’est lui qui assure que tous les développeurs et la CI utilisent exactement les mêmes versions. Sans lui, la reproductibilité n’est pas garantie.

Définir ses outputs : devShells, packages, apps

La fonction outputs retourne un attribute set dont les clés suivent une convention standardisée. Voici un flake complet avec les trois outputs les plus courants :

{
  description = "Projet Python avec devShell et package";

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

  outputs = { self, nixpkgs }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
      python = pkgs.python312;
    in {
      # Environnement de développement
      devShells.${system}.default = pkgs.mkShell {
        packages = [
          (python.withPackages (ps: [ ps.requests ps.pytest ]))
          pkgs.curl
          pkgs.jq
        ];
        shellHook = ''
          echo "Environnement Python pret"
          export PROJECT_NAME=mon-projet
        '';
      };

      # Paquet construisible
      packages.${system}.default = pkgs.writeShellScriptBin "hello-projet" ''
        echo "Bienvenue dans mon-projet !"
      '';

      # Application exécutable
      apps.${system}.default = {
        type = "app";
        program = "${self.packages.${system}.default}/bin/hello-projet";
      };
    };
}

Les types d’outputs standards

Output	Commande associée	Rôle
devShells.<system>.default	nix develop	Environnement de développement
packages.<system>.default	nix build	Paquet à construire
apps.<system>.default	nix run	Application à exécuter
overlays.default	—	Modification de nixpkgs
nixosConfigurations.<nom>	nixos-rebuild	Configuration NixOS complète
nixosModules.default	—	Module NixOS réutilisable

Glissez pour voir

Pourquoi legacyPackages ?

L’attribut nixpkgs.legacyPackages.${system} donne accès à tous les paquets de nixpkgs. Le nom « legacy » est trompeur — c’est l’accès standard. Il est nommé ainsi car la structure de nixpkgs ne respecte pas complètement le schéma strict des flakes (qui attendrait packages).

Construire, exécuter et inspecter un flake

Visualiser la structure avec nix flake show

nix flake show

git+file:///home/lab/demo-flake-devshell
├───apps
│   └───x86_64-linux
│       └───default: app
├───devShells
│   └───x86_64-linux
│       └───default: development environment 'nix-shell'
└───packages
    └───x86_64-linux
        └───default: package 'hello-projet'

Consulter les métadonnées avec nix flake metadata

nix flake metadata

Resolved URL:  git+file:///home/lab/demo-flake-devshell
Description:   Projet Python avec devShell et package
Path:          /nix/store/d9pvgm44r0dnqlg8whgdpzd7q73ihayj-source
Inputs:
└───nixpkgs: github:nixos/nixpkgs/4c1018dae018162ec878d42fec712642d214fdfa (2026-04-09)

Entrer dans l’environnement de développement

nix develop

Environnement Python pret

Le shellHook s’exécute et toutes les dépendances sont disponibles :

python3 --version && echo $PROJECT_NAME

Python 3.12.13
mon-projet

Construire un paquet

nix build

building '/nix/store/8s05glip2sx5zb5gj1n6l0r2ggjn7h96-hello-projet.drv'...

Le résultat est un lien symbolique ./result pointant vers le store :

ls -la result

result -> /nix/store/10s5j3mfdg22k1597x580qrhprnzcjwb-hello-projet

./result/bin/hello-projet

Bienvenue dans mon-projet !

Exécuter directement avec nix run

nix run

Bienvenue dans mon-projet !

nix run combine nix build + exécution du binaire par défaut en une seule commande.

Vérifier la validité du flake

nix flake check

checking flake output 'devShells'...
checking derivation devShells.x86_64-linux.default...
checking flake output 'packages'...
checking derivation packages.x86_64-linux.default...
checking flake output 'apps'...
checking app 'apps.x86_64-linux.default'...
all checks passed!

nix flake check évalue toutes les dérivations et vérifie la conformité des outputs. Indispensable dans une pipeline CI.

Mettre à jour les dépendances

Pour mettre à jour tous les inputs :

nix flake update

Pour mettre à jour un seul input :

nix flake update nixpkgs

Après la mise à jour, vérifiez le diff de flake.lock avec git diff flake.lock avant de commiter.

Syntaxe dépréciée

L’ancienne syntaxe nix flake lock --update-input nixpkgs est dépréciée depuis Nix 2.19. Utilisez nix flake update nixpkgs à la place.

Convertir un projet shell.nix existant vers les flakes

Si vous avez un shell.nix classique qui utilise <nixpkgs>, voici comment le migrer vers un flake.

Avant : shell.nix classique

shell.nix

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  packages = with pkgs; [
    python312
    python312Packages.requests
    git
    curl
  ];

  shellHook = ''
    echo "Environnement dev classique"
  '';
}

Ce fichier fonctionne avec nix-shell, mais les versions dépendent du channel actif sur chaque machine.

Après : flake.nix

{
  description = "Projet migre de shell.nix vers flake";

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

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

        shellHook = ''
          echo "Environnement dev (flake, nixos-24.11)"
        '';
      };
    };
}

Les différences concrètes

Aspect	shell.nix	flake.nix
Source nixpkgs	<nixpkgs> (channel local)	github:nixos/nixpkgs/nixos-24.11 (verrouillé)
Versions obtenues	Varient selon la machine	Identiques partout
Commande d’entrée	nix-shell	nix develop
Verrouillage	Aucun (ou fetchTarball manuel)	Automatique (flake.lock)

Glissez pour voir

Le résultat avec nixos-24.11 verrouillé :

nix develop --command bash -c "python3 --version && git --version"

Python 3.12.8
git version 2.47.2

Tandis qu’avec nixos-unstable, les mêmes paquets donnent Python 3.12.13 et git 2.53.0.

Migration progressive

Vous pouvez garder votre shell.nix existant en parallèle du flake.nix. Les utilisateurs sans flakes continuent avec nix-shell, les autres passent à nix develop. Le paquet flake-compat permet de maintenir cette compatibilité entre les deux approches.

Supporter plusieurs architectures

Par défaut, un flake cible un seul system (typiquement "x86_64-linux"). Pour supporter Linux et macOS sur x86_64 et ARM, utilisez flake-utils :

Avec flake-utils

{
  description = "Flake multi-architecture";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = [ pkgs.jq pkgs.curl ];
        };

        packages.default = pkgs.hello;
      }
    );
}

eachDefaultSystem itère automatiquement sur les quatre systèmes standards :

nix flake show

├───devShells
│   ├───aarch64-darwin
│   │   └───default omitted (use '--all-systems' to show)
│   ├───aarch64-linux
│   │   └───default omitted (use '--all-systems' to show)
│   ├───x86_64-darwin
│   │   └───default omitted (use '--all-systems' to show)
│   └───x86_64-linux
│       └───default: development environment 'nix-shell'
└───packages
    ├───aarch64-darwin
    │   └───default omitted (use '--all-systems' to show)
    ├───aarch64-linux
    │   └───default omitted (use '--all-systems' to show)
    ├───x86_64-darwin
    │   └───default omitted (use '--all-systems' to show)
    └───x86_64-linux
        └───default: package 'hello-2.12.3'

Sans flake-utils

Si vous préférez éviter la dépendance à flake-utils, utilisez genAttrs de nixpkgs :

outputs = { self, nixpkgs }:
  let
    supportedSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" ];
    forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
    pkgsFor = system: nixpkgs.legacyPackages.${system};
  in {
    packages = forAllSystems (system: {
      default = (pkgsFor system).hello;
    });

    devShells = forAllSystems (system: {
      default = (pkgsFor system).mkShell {
        packages = [ (pkgsFor system).hello ];
      };
    });
  };

Intégrer les flakes avec direnv

direnv active automatiquement l’environnement du flake quand vous entrez dans le répertoire du projet. Plus besoin de taper nix develop manuellement.

1. Installez direnv et nix-direnv :

   nix profile install nixpkgs#direnv nixpkgs#nix-direnv

2. Configurez votre shell (ajoutez à ~/.bashrc ou ~/.zshrc) :

   eval "$(direnv hook bash)"    # ou hook zsh
   source $HOME/.nix-profile/share/nix-direnv/direnvrc

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

   echo "use flake" > .envrc
   direnv allow

4. À chaque cd dans le projet, l’environnement se charge automatiquement.

Cache direnv

nix-direnv met en cache le résultat de l’évaluation. Le premier chargement prend quelques secondes, mais les suivants sont quasi instantanés — même après un redémarrage du terminal.

Structure recommandée d’un projet avec flakes

Pour un projet réel, organisez vos fichiers Nix dans un sous-répertoire :

• Répertoiremon-projet/

  • flake.nix Point d’entrée principal
  • flake.lock Versions verrouillées (généré)
  • .envrc Pour direnv (use flake)
  • Répertoirenix/

    • Répertoiredevshells/

      • default.nix Définition du devShell
    • Répertoirepackages/

      • default.nix Définitions de paquets
    • Répertoireoverlays/

      • default.nix Overlays personnalisés
  • Répertoiresrc/ Code source de l’application

    • …

Le flake.nix importe ensuite ces fichiers :

{
  description = "Projet organisé";

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

  outputs = { self, nixpkgs }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      devShells.${system}.default = import ./nix/devshells/default.nix { inherit pkgs; };
      packages.${system}.default = import ./nix/packages/default.nix { inherit pkgs; };
    };
}

Comparaison flakes et channels

Aspect	Channels (classique)	Flakes
Verrouillage	Manuel (fetchTarball + hash)	Automatique (flake.lock)
Reproductibilité	Difficile à garantir	Garantie par défaut
Structure	Libre (convention par projet)	Standardisée (inputs/outputs)
Composition	Complexe (imports manuels)	Native (follows, multi-inputs)
Évaluation	Impure (accès au système de fichiers)	Pure (hermétique)
Commandes	nix-env, nix-shell, nix-build	nix develop, nix build, nix run
Mise à jour	nix-channel --update (global)	nix flake update (par projet)
CI/CD	Configuration manuelle	Structure prédictible

Glissez pour voir

Dépannage courant

Symptôme	Cause probable	Solution
error: experimental feature 'flakes' is disabled	Flakes non activés	Ajouter experimental-features = nix-command flakes dans ~/.config/nix/nix.conf
error: getting status of '/flake.nix': No such file or directory	Fichier non suivi par Git	git add flake.nix
error: path '/nix/store/…' is not valid	Fichier manquant dans Git	git add <fichier-manquant>
warning: Git tree '…' is dirty	Modifications non commitées	git add -A && git commit (ou ignorer l’avertissement)
Build échoue en CI mais pas en local	flake.lock absent ou pas à jour	git add flake.lock && git commit
--update-input affiche un warning	Syntaxe dépréciée	Utiliser nix flake update <input>

Glissez pour voir

À retenir

• Un flake = flake.nix (déclaration) + flake.lock (verrouillage) dans un dépôt Git
• Les inputs déclarent les sources ; follows évite la duplication
• Les outputs produisent des devShells, packages, apps — avec une convention standardisée
• nix develop remplace nix-shell, nix build remplace nix-build, nix run exécute directement
• nix flake check valide la structure — indispensable en CI
• nix flake update met à jour les inputs ; le diff de flake.lock sert de revue
• flake-utils simplifie le support multi-architecture
• direnv + nix-direnv activent l’environnement automatiquement

Prochaines étapes

NixOS : le système déclaratif Découvrez NixOS, le système d'exploitation entièrement déclaratif construit sur Nix et les flakes.

Environnements de développement Revenez aux bases de mkShell, nix-shell et nix develop pour les environnements de développement.

Import, factorisation et pinning Comprenez le pinning classique avec fetchTarball et la factorisation avec import — les prédécesseurs des flakes.

×

📖 Voir la documentation →