Skip to content

Imports and Profiles

Overview

Imports compose NixOS configuration from many modules. Each path in imports = [ ./hw.nix … ] is evaluated as a full module—same shape as configuration.nix, with its own imports, options, and config. NixOS profiles are predefined modules shipped under nixpkgs/nixos/modules/profiles/; you pull them in the same way. They are not the same thing as user or system profiles managed by nix-env or nixos-rebuild.

Details

How imports compose. The module system merges every imported module into one evaluated config. Your entry module stays thin: it lists fragments and sets host-specific overrides. nixpkgs already loads a default module set from modules/module-list.nix; you only add imports for your own files, optional upstream profiles, or third-party modules.

Static import resolution. imports is resolved before the module fixpoint runs—before merged config exists. Paths and import lists must therefore be known statically. You cannot choose an import based on config.services.x.enable or other option values. When you need values from outside the module tree (flake inputs, computed paths), pass them through specialArgs or _module.args so they are available as function arguments during import resolution—not by reading config inside imports.

Splitting by concern. A common layout keeps one entry module and imports focused fragments:

Fragment Typical contents
hardware-configuration.nix Disks, filesystems, kernel modules (often generated at install)
users.nix users.users, SSH keys, groups
desktop.nix Display manager, desktop session, fonts
services.nix Web servers, databases, networking services

The exact filenames are yours; the pattern is one concern per module, composed through imports.

NixOS profiles vs package profiles. NixOS profiles are .nix files in nixpkgs nixos/modules/profiles/ that set bundles of options—for example headless.nix for cloud VMs, minimal.nix for a smaller default set, installation-device.nix for install media, and clone-config.nix for editable live-system configs. Importing a profile is importing a module; it does not create or switch a Nix profile symlink or add a generation. Profiles are not enabled with a fictional profiles.*.enable option—add them to imports. The shared word profile is unfortunate; keep module profiles and store profiles separate when reading configs and docs.

Referencing nixpkgs profiles. Inside a NixOS module, modulesPath points at the nixpkgs NixOS modules tree (provided via specialArgs). Use it instead of hard-coding <nixpkgs/nixos/modules/…> so paths stay correct across channels and flakes:

{ modulesPath, ... }: {
  imports = [ (modulesPath + "/profiles/headless.nix") ];
}

The manual also shows <nixpkgs/nixos/modules/profiles/profile-name.nix> for classic installs where that path resolves via NIX_PATH.

Boundaries (what this page is not)

  • Flake inputs—pinning nixpkgs and third-party flakes.
  • Module types and option merge semantics.
  • Secrets—encrypted deploy-time material and activation wiring.

Examples

Entry module mixing local fragments and an upstream profile:

{ config, pkgs, modulesPath, ... }: {
  imports = [
    ./hardware-configuration.nix
    ./users.nix
    ./services.nix
    (modulesPath + "/profiles/headless.nix")
  ];

  networking.hostName = "edge-01";
  # host-specific overrides …
}

Each imported file is a module on its own—for example, ./users.nix might be:

{ ... }: {
  users.users.alice = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };
}

For module structure and merge helpers, see Writing a module.

References

See also