Skip to content

nixosConfigurations

Overview

nixosConfigurations.<name> is the flake output that exposes a complete NixOS system configuration. Each name (often the machine hostname) maps to the result of nixpkgs.lib.nixosSystem, which evaluates the module system and produces a closed system closure. The Nix CLI and nixos-rebuild consume this output to build, check, and switch generations on real hardware.

This page covers flake wiring—how inputs, modules, and output names connect. Module semantics, configuration.nix structure, and activation mechanics live under 09-nixos; see Inputs and outputs for how nixosConfigurations fits the general output schema.

Details

Defining a configuration. Wire each host with nixpkgs.lib.nixosSystem:

nixosConfigurations.<name> = nixpkgs.lib.nixosSystem {
  modules = [
    ./configuration.nix
    # optional: other modules, Home Manager’s NixOS module, etc.
  ];
  specialArgs = { inherit inputs; }; # optional: pass flake inputs into modules
};

Documented arguments (from the Nixpkgs flake):

Argument Role
modules List of paths or inline modules merged into the system
specialArgs Extra args available to every module (not overridable via modules)
modulesLocation Default location for non-path modules (error messages)

system and pkgs are legacy aliases for nixpkgs.hostPlatform and nixpkgs.pkgs. Prefer setting the platform in hardware-configuration.nix (or an equivalent module) rather than relying on the top-level system argument.

nixosSystem returns an evaluated NixOS config; .config.system.build.toplevel is the system derivation—the same artifact nixos-rebuild activates.

Inputs and pinning. Declare inputs.nixpkgs.url on a release branch (for example github:NixOS/nixpkgs/nixos-26.05) so system builds share a pinned package set with flake.lock. Pass other inputs into modules via specialArgs when modules need inputs.home-manager, custom flakes, or vendored sources.

Home Manager. Compose user environments on the same system by importing home-manager.nixosModules.home-manager (and a per-user module) in the modules list. Standalone HM flake wiring is covered in homeConfigurations; here HM is just another module source for nixosSystem.

Checking. nix flake check verifies that each nixosConfigurations.<name>.config.system.build.toplevel evaluates to a valid derivation (experimental nix-command / flakes). Use this in CI before deploying.

Building without switching. Produce the system closure without activating it:

nix build .#nixosConfigurations.<name>.config.system.build.toplevel

The resulting symlink (or ./result) is the same store path nixos-rebuild switch would register as a new generation.

Applying on a machine. On the target system (with flakes enabled):

sudo nixos-rebuild switch --flake .#<name>

Omitting #<name> makes nixos-rebuild look up nixosConfigurations.<current-hostname>. Use boot or test instead of switch for reboot-required or non-persistent trial activation; see rebuild: switch, boot, test. Remote hosts use the same flake reference with --target-host and related flags—remote deploy.

Multiple machines. One flake commonly defines several nixosConfigurations keys (laptop, server, pi) sharing base modules and differing only in hardware or role-specific imports. Each name is an independent output addressable as .#<name> in rebuild and build commands.

Examples

Minimal flake with a pinned nixpkgs input and one NixOS configuration:

{
  description = "Example NixOS flake";

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

  outputs = { self, nixpkgs, ... }@inputs: {
    nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit inputs; };
      modules = [ ./configuration.nix ];
    };
  };
}

./configuration.nix is a normal NixOS module (often importing ./hardware-configuration.nix); see configuration.nix. After evaluation succeeds, deploy with:

sudo nixos-rebuild switch --flake .#hostname

References

See also