From 0a8d50edf28d537ce7538fbbf207fa7939d41abc Mon Sep 17 00:00:00 2001 From: Austin Horstman Date: Mon, 20 Apr 2026 09:01:34 -0500 Subject: [PATCH] docs/nix-flakes: clarify extraSpecialArgs usage Explain when to use extraSpecialArgs versus _module.args in the flake setup guides, and keep the generated standalone fixture aligned with the updated template output. --- docs/manual/nix-flakes/nix-darwin.md | 15 ++++++++-- docs/manual/nix-flakes/nixos.md | 15 ++++++++-- docs/manual/nix-flakes/standalone.md | 30 +++++++++++++++++++ templates/nix-darwin/flake.nix | 6 ++-- templates/nixos/flake.nix | 6 ++-- templates/standalone/flake.nix | 5 ++-- .../standalone/alice-flake-init.nix | 5 ++-- 7 files changed, 62 insertions(+), 20 deletions(-) diff --git a/docs/manual/nix-flakes/nix-darwin.md b/docs/manual/nix-flakes/nix-darwin.md index 320656b61..aae727a22 100644 --- a/docs/manual/nix-flakes/nix-darwin.md +++ b/docs/manual/nix-flakes/nix-darwin.md @@ -25,10 +25,8 @@ to that of NixOS. The `flake.nix` would be: { home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; + home-manager.extraSpecialArgs = { inherit inputs; }; home-manager.users.jdoe = ./home.nix; - - # Optionally, use home-manager.extraSpecialArgs to pass - # arguments to home.nix } ]; }; @@ -37,6 +35,17 @@ to that of NixOS. The `flake.nix` would be: } ``` +Use `home-manager.extraSpecialArgs` to pass arguments from your flake to +`home.nix` and any imported Home Manager modules. For example, the +configuration above makes the complete `inputs` attrset available to modules, +so they can declare arguments such as `{ inputs, ... }:`. + +The lower-level mechanism behind this is `_module.args`. Set +`_module.args.` from inside a module only when you need to provide a +module argument from within the module graph itself. For values that originate +outside the module graph, such as flake inputs, prefer +`home-manager.extraSpecialArgs`. + and it is also rebuilt with the nix-darwin generations. The rebuild command here may be `darwin-rebuild switch --flake `. diff --git a/docs/manual/nix-flakes/nixos.md b/docs/manual/nix-flakes/nixos.md index 1e7f21e34..b04ebdbc4 100644 --- a/docs/manual/nix-flakes/nixos.md +++ b/docs/manual/nix-flakes/nixos.md @@ -23,10 +23,8 @@ be as follows: { home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; + home-manager.extraSpecialArgs = { inherit inputs; }; home-manager.users.jdoe = ./home.nix; - - # Optionally, use home-manager.extraSpecialArgs to pass - # arguments to home.nix } ]; }; @@ -35,6 +33,17 @@ be as follows: } ``` +Use `home-manager.extraSpecialArgs` to pass arguments from your flake to +`home.nix` and any imported Home Manager modules. For example, the +configuration above makes the complete `inputs` attrset available to modules, +so they can declare arguments such as `{ inputs, ... }:`. + +The lower-level mechanism behind this is `_module.args`. Set +`_module.args.` from inside a module only when you need to provide a +module argument from within the module graph itself. For values that originate +outside the module graph, such as flake inputs, prefer +`home-manager.extraSpecialArgs`. + The Home Manager configuration is then part of the NixOS configuration and is automatically rebuilt with the system when using the appropriate command for the system, such as diff --git a/docs/manual/nix-flakes/standalone.md b/docs/manual/nix-flakes/standalone.md index 4ab659542..9d2c04a5b 100644 --- a/docs/manual/nix-flakes/standalone.md +++ b/docs/manual/nix-flakes/standalone.md @@ -20,6 +20,36 @@ $ nix run home-manager/release-25.11 -- init --switch This will generate a `flake.nix` and a `home.nix` file in `~/.config/home-manager`, creating the directory if it does not exist. +If you need to pass additional values from your flake to `home.nix` or any +imported Home Manager modules, use `extraSpecialArgs` in the call to +`home-manager.lib.homeManagerConfiguration`: + +``` nix +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + home-manager.url = "github:nix-community/home-manager"; + home-manager.inputs.nixpkgs.follows = "nixpkgs"; + }; + + outputs = inputs@{ nixpkgs, home-manager, ... }: { + homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; + extraSpecialArgs = { inherit inputs; }; + modules = [ ./home.nix ]; + }; + }; +} +``` + +Any attribute in `extraSpecialArgs` becomes a module argument, so `home.nix` +or imported modules can declare arguments such as `{ inputs, ... }:`. + +The lower-level mechanism behind this is `_module.args`. Set +`_module.args.` from inside a module only when you need to provide a +module argument from within the module graph itself. For values that originate +outside the module graph, such as flake inputs, prefer `extraSpecialArgs`. + If you omit the `--switch` option then the activation will not happen. This is useful if you want to inspect and edit the configuration before activating it. diff --git a/templates/nix-darwin/flake.nix b/templates/nix-darwin/flake.nix index 315796135..f40173e29 100644 --- a/templates/nix-darwin/flake.nix +++ b/templates/nix-darwin/flake.nix @@ -10,7 +10,7 @@ }; outputs = - { + inputs@{ home-manager, darwin, ... @@ -25,10 +25,8 @@ { home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; + home-manager.extraSpecialArgs = { inherit inputs; }; home-manager.users.jdoe = ./home.nix; - - # Optionally, use home-manager.extraSpecialArgs to pass - # arguments to home.nix } ]; }; diff --git a/templates/nixos/flake.nix b/templates/nixos/flake.nix index 1d9966d48..007f6d618 100644 --- a/templates/nixos/flake.nix +++ b/templates/nixos/flake.nix @@ -8,7 +8,7 @@ }; outputs = - { nixpkgs, home-manager, ... }: + inputs@{ nixpkgs, home-manager, ... }: { nixosConfigurations = { hostname = nixpkgs.lib.nixosSystem { @@ -19,10 +19,8 @@ { home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; + home-manager.extraSpecialArgs = { inherit inputs; }; home-manager.users.jdoe = ./home.nix; - - # Optionally, use home-manager.extraSpecialArgs to pass - # arguments to home.nix } ]; }; diff --git a/templates/standalone/flake.nix b/templates/standalone/flake.nix index f5c92967c..d09dd3cd1 100644 --- a/templates/standalone/flake.nix +++ b/templates/standalone/flake.nix @@ -11,7 +11,7 @@ }; outputs = - { nixpkgs, home-manager, ... }: + inputs@{ nixpkgs, home-manager, ... }: let system = "x86_64-linux"; pkgs = nixpkgs.legacyPackages.${system}; @@ -24,8 +24,7 @@ # the path to your home.nix. modules = [ ./home.nix ]; - # Optionally use extraSpecialArgs - # to pass through arguments to home.nix + extraSpecialArgs = { inherit inputs; }; }; }; } diff --git a/tests/integration/standalone/alice-flake-init.nix b/tests/integration/standalone/alice-flake-init.nix index 31e999873..dd08f4cb6 100644 --- a/tests/integration/standalone/alice-flake-init.nix +++ b/tests/integration/standalone/alice-flake-init.nix @@ -11,7 +11,7 @@ }; outputs = - { nixpkgs, home-manager, ... }: + inputs@{ nixpkgs, home-manager, ... }: let system = "x86_64-linux"; pkgs = nixpkgs.legacyPackages.${system}; @@ -24,8 +24,7 @@ # the path to your home.nix. modules = [ ./home.nix ]; - # Optionally use extraSpecialArgs - # to pass through arguments to home.nix + extraSpecialArgs = { inherit inputs; }; }; }; }