Skip to content

hardware-configuration.nix

Overview

hardware-configuration.nix is a NixOS module written by nixos-generate-config from the machine’s currently mounted filesystems and detected hardware. It records facts that depend on physical layout—fileSystems, swapDevices, initrd kernel modules—not host policy. A typical install imports it from configuration.nix and keeps lasting customizations in that entry module instead.

Details

Run nixos-generate-config during installation with --root /mnt (after mounting the target filesystems under /mnt), or on an existing system without --root to refresh hardware facts under /etc/nixos. The tool always rewrites hardware-configuration.nix. On a fresh install it also writes a starter configuration.nix that imports the hardware file; an existing configuration.nix is left alone unless you pass --force. Use --show-hardware-config to print the hardware module to stdout without writing files.

What it usually contains. The scan reflects mount points active when the command runs: root and other fileSystems entries, swapDevices, and boot-related lists such as boot.initrd.availableKernelModules, boot.initrd.kernelModules, boot.kernelModules, and boot.extraModulePackages. On bare metal it typically imports (modulesPath + "/installer/scan/not-detected.nix") and may set CPU microcode options; under QEMU/KVM it may import qemu-guest.nix. Other detections can enable guest helpers (for example VirtualBox or Hyper-V). These values must be correct for the system to mount / in early boot—see the NixOS manual’s installation chapter. If initrd modules are still wrong after generation, the manual’s recovery path is to fix options in configuration.nix and rerun nixos-install.

Generated files open with a warning that future nixos-generate-config runs will overwrite them; the NixOS manual says you generally should not modify the file for lasting customizations. Put stable overrides in configuration.nix instead (module merge / lib.mkForce when needed). Regenerating wipes hand-edited lines in the hardware file.

ESP mount points on UEFI. Both systemd-boot and GRUB on NixOS expect the EFI System Partition on /boot by default. The generator derives fileSystems from whatever is mounted when you run it; if the live environment mounted the ESP elsewhere (for example /boot/efi), the generated entry may not match NixOS bootloader conventions. Remount the ESP on /boot before generating, or adjust the mount point in hardware-configuration.nix before the first build—see Partitioning and bootloaders. That ESP check is one of the few cases where the manuals explicitly call for editing the generated file.

Not the same as nixos-hardware. nixos-hardware is a separate collection of optional NixOS modules for specific machines. It is not what nixos-generate-config writes; you import a profile yourself when you want vendor- or model-specific tweaks, alongside this generated file.

This page documents the generated hardware module only—not partitioning recipes or a configuration.nix tutorial.

Examples

Typical import in the entry module (from generated configuration.nix):

{ config, pkgs, ... }: {
  imports = [ ./hardware-configuration.nix ];
  # host-specific options …
}

Illustrative excerpt shaped like a generated hardware-configuration.nix (devices and modules vary; do not copy as-is):

# Do not modify this file!  It was generated by ‘nixos-generate-config’
# and may be overwritten by future invocations.  Please make changes
# to /etc/nixos/configuration.nix instead.
{ config, lib, pkgs, modulesPath, ... }: {
  imports = [ (modulesPath + "/installer/scan/not-detected.nix") ];

  boot.initrd.availableKernelModules = [ "nvme" "xhci_pci" "ahci" ];
  boot.initrd.kernelModules = [ ];
  boot.kernelModules = [ "kvm-intel" ];
  boot.extraModulePackages = [ ];

  fileSystems."/" = {
    device = "/dev/disk/by-uuid/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
    fsType = "ext4";
  };

  swapDevices = [ { device = "/dev/disk/by-uuid/ffffffff-0000-1111-2222-333333333333"; } ];
}

Regenerate after disk or hardware changes:

# During install (target root mounted at /mnt)
sudo nixos-generate-config --root /mnt

# On a running system (overwrites hardware-configuration.nix only)
sudo nixos-generate-config

References

See also