Home-Manager : gérer son environnement utilisateur sous NixOS

📍 Guide principal : NixOS pour développeurs et serveurs : reproductibilité totale en 2026
Ce tutoriel s’inscrit dans la série NixOS. Si l’idée de gérer son OS en fichier déclaratif vous est nouvelle, lisez d’abord le guide principal pour la vue d’ensemble.

Pourquoi sortir ses dotfiles d’un dépôt git classique pour les confier à Home-Manager

La plupart des développeurs gèrent leurs dotfiles avec un dépôt git, des liens symboliques et un script install.sh. Le résultat marche, mais il a deux limites : il ne gère que les fichiers de configuration, pas les paquets associés (zsh suppose que vous avez déjà installé zsh, neovim suppose ses plugins déjà clonés), et il ne se rejoue pas atomiquement — un fichier corrompu se règle au cas par cas. Home-Manager change la perspective : il décrit l’environnement utilisateur comme un attrset Nix, télécharge les paquets, génère les fichiers de config à partir de templates typés, et gère des générations exactement comme NixOS gère le système.

Concrètement, vous aurez un fichier home.nix qui déclare votre zsh, votre neovim avec ses plugins, votre git avec votre nom et email, vos clés SSH, vos polices Nerd Fonts, vos alias. Un home-manager switch applique l’ensemble. Sur une nouvelle machine, vous installez NixOS, vous clonez votre flake, vous lancez la même commande, et vous retrouvez le même environnement, à la décimale près.

Prérequis

• NixOS 25.11 installé (suivez le tutoriel d’installation), ou Nix sur Linux/macOS.
• Flakes activés — sinon voir Flakes : essentiels.
• Un dépôt git pour vos dotfiles.

Étape 1 — Choisir son mode d’installation

Home-Manager s’installe selon deux modes principaux. Standalone : un binaire home-manager indépendant. C’est le mode souple, recommandé pour itérer plus vite que nixos-rebuild ne le permet. Module NixOS : Home-Manager devient une partie intégrante de votre nixos-rebuild switch. Plus cohérent en production, mais une erreur dans home.nix bloque le rebuild système.

Ce tutoriel suit le mode standalone. La section « Variante » en fin d’article montre la conversion vers le module NixOS.

Étape 2 — Initialiser le flake home-manager

mkdir -p ~/dotfiles && cd ~/dotfiles
git init
nix flake init

Remplacez le contenu de flake.nix par un squelette pointant la branche release-25.11 de Home-Manager :

{
  description = "Mes dotfiles avec Home-Manager";
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    home-manager = {
      url = "github:nix-community/home-manager/release-25.11";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  outputs = { self, nixpkgs, home-manager, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      homeConfigurations.alice = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [ ./home.nix ];
      };
    };
}

Le bloc inputs.home-manager.inputs.nixpkgs.follows garantit que Home-Manager utilise la même nixpkgs que votre flake, évitant les conflits de versions.

Étape 3 — Écrire son premier home.nix

{ config, pkgs, ... }:
{
  home.username = "alice";
  home.homeDirectory = "/home/alice";
  home.stateVersion = "25.11";

  home.packages = with pkgs; [
    ripgrep fd bat eza fzf jq htop bottom
    nerd-fonts.fira-code
  ];

  programs.zsh = {
    enable = true;
    autosuggestion.enable = true;
    syntaxHighlighting.enable = true;
    shellAliases = {
      ll = "eza -la --git";
      gst = "git status";
    };
  };

  programs.starship.enable = true;
  programs.git = {
    enable = true;
    userName = "Alice Dupont";
    userEmail = "alice@exemple.fr";
  };
  programs.direnv = {
    enable = true;
    nix-direnv.enable = true;
  };
  programs.neovim = {
    enable = true;
    defaultEditor = true;
    plugins = with pkgs.vimPlugins; [
      telescope-nvim
      nvim-treesitter.withAllGrammars
      gruvbox-nvim
    ];
  };
  programs.home-manager.enable = true;
}

Chaque programs.X active le programme et déclare ses options de façon typée — Home-Manager génère ensuite ~/.config/zsh/.zshrc, ~/.config/git/config, etc.

Étape 4 — Premier home-manager switch

nix run home-manager/release-25.11 -- switch --flake .#alice

La première exécution prend quelques minutes : Home-Manager télécharge les paquets, compile la configuration zsh/starship/neovim, et écrit les fichiers générés dans votre $HOME. À la fin, le shell affiche « Activation finished successfully ».

Étape 5 — Lister les générations et faire un rollback

home-manager list-generations

La sortie affiche un horodatage et un chemin du store par génération. Pour revenir à une ancienne, exécutez son script activate. home-manager expire-generations '-7 days' nettoie les vieilles.

Étape 6 — Gérer un fichier que Home-Manager ne connaît pas

Tous les programmes ne sont pas exposés en programs.X. Pour un fichier maison, xdg.configFile ou home.file :

xdg.configFile."tmux/tmux.conf".text = ''
  set -g mouse on
  set -g default-terminal "tmux-256color"
'';

Le contenu est stocké dans le store et un lien symbolique pointe depuis votre $HOME.

Étape 7 — Mettre à jour

cd ~/dotfiles
nix flake update
home-manager switch --flake .#alice

Si le rebuild échoue, revenez à l’ancien flake.lock avec git checkout flake.lock.

Étape 8 — Déployer sur une nouvelle machine

git clone https://github.com/votrenom/dotfiles ~/dotfiles
cd ~/dotfiles
nix run home-manager/release-25.11 -- switch --flake .#alice
exec zsh

Vous retrouvez en quelques minutes votre environnement complet.

Erreurs fréquentes

Variante : Home-Manager comme module NixOS

Pour fusionner Home-Manager dans le rebuild NixOS, ajoutez Home-Manager comme input du flake système et incluez le module dans nixosConfigurations :

nixosConfigurations.thanos = nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  modules = [
    ./configuration.nix
    home-manager.nixosModules.home-manager
    {
      home-manager.useGlobalPkgs = true;
      home-manager.useUserPackages = true;
      home-manager.users.alice = import ./home.nix;
    }
  ];
};

Désormais, nixos-rebuild switch --flake .#thanos applique aussi votre home.nix.

Comprendre comment Home-Manager génère les fichiers

Pour vraiment maîtriser l’outil, il faut savoir ce qui se passe quand vous déclarez programs.zsh.shellAliases.ll = "eza -la". Premièrement, le module programs.zsh traduit votre attrset en un texte de configuration zsh. Deuxièmement, le module produit une dérivation Nix qui construit ce fichier dans /nix/store/abc...-zshrc. Troisièmement, à l’activation, Home-Manager pose un lien symbolique ~/.config/zsh/.zshrc qui pointe vers ce fichier du store. Quatrièmement, vos vieux fichiers non gérés sont déplacés dans ~/.home-manager-backup-<timestamp>.

Cette mécanique a deux conséquences. Vos fichiers de config sont en lecture seule ; tenter de les éditer renvoie une erreur. Et les changements ne prennent effet qu’après home-manager switch. Cette contrainte est délibérée — c’est le prix de la reproductibilité.

Le système de modules en détail

Comme NixOS, Home-Manager utilise le système de modules de nixpkgs. Chaque option a un type explicite (str, bool, int, listOf, attrsOf, submodule), une valeur par défaut, et une description.

home-manager option programs.zsh
man home-configuration.nix    # le manuel offline complet

Apprenez à utiliser home-manager option dès le début ; c’est la commande qui transforme la frustration en autonomie.

Séparer la config en plusieurs fichiers via imports

Quand home.nix dépasse 200 lignes, l’éclater devient nécessaire :

~/dotfiles/
├── flake.nix
├── home.nix
└── modules/
    ├── shell.nix
    ├── editor.nix
    ├── git.nix
    └── desktop.nix

Dans home.nix, vous remplacez tout par imports = [ ./modules/shell.nix ./modules/editor.nix ];. Le système de modules merge intelligemment : si deux fichiers déclarent home.packages, les listes sont concaténées.

Comparer Home-Manager à chezmoi, GNU Stow, dotbot

GNU Stow crée des liens symboliques ; il ne gère ni les paquets ni les générations. chezmoi gère les variations par hôte avec élégance, mais ne touche pas aux paquets non plus. dotbot applique un YAML déclaratif, mais reste limité aux fichiers et aux symlinks. Home-Manager fait plus que les trois : il gère les paquets, les fichiers de config typés, et les générations atomiques avec rollback. Le coût d’entrée est plus élevé — il faut apprendre Nix — mais une fois le pli pris, vous obtenez un environnement complet déclaratif.

Plusieurs hôtes : laptop, desktop, serveur

homeConfigurations = {
  alice-laptop = home-manager.lib.homeManagerConfiguration {
    inherit pkgs;
    modules = [ ./home.nix ./hosts/laptop.nix ];
  };
  alice-serveur = home-manager.lib.homeManagerConfiguration {
    inherit pkgs;
    modules = [ ./home.nix ./hosts/serveur.nix ];
  };
};

Sur le laptop, home-manager switch --flake .#alice-laptop. Sur le serveur, --flake .#alice-serveur. Le fichier par hôte peut désactiver Neovim avec ses plugins lourds, ne garder qu’un shell minimaliste.

Foire aux questions

Home-Manager remplace-t-il complètement mon dépôt git de dotfiles ? Oui. Plus besoin de scripts d’installation maison.

Que faire si un programme n’a pas de module programs.X ? Trois options : home.file ou xdg.configFile pour générer manuellement, écrire un module soi-même, soumettre une PR au dépôt nix-community/home-manager.

Mes secrets doivent-ils être dans home.nix ? Non, jamais en clair. Combinez avec agenix pour des secrets chiffrés.

Puis-je utiliser Home-Manager sur macOS ? Oui, en mode standalone. Beaucoup d’options sont communes ; nix-darwin gère le système macOS lui-même.

Suite logique

Avec Home-Manager en place, votre environnement utilisateur est aussi déclaratif que votre système. Le tutoriel suivant naturel est Dev-shells par projet avec nix develop. Pour gérer les secrets de votre home.nix, Gérer les secrets avec agenix est la suite. Le guide principal NixOS reste l’index.

Références officielles

• Manuel officiel Home-Manager.
• github.com/nix-community/home-manager.
• Liste exhaustive des options.
• search.nixos.org/packages.