Modules

A .nix file contains a single expression, which means it can be evaluated to a single value. A module is a particular kind of Nix expression which can

• import other modules,
• declare a set of options you can change to configure its behaviour,
• and define a set of options that were declared in other modules.

It's a set, or a function that returns a set, that can look like this:

{ ... }: {
  imports = [
    # import paths
  ];

  options = {
    # option declarations
  };

  config = {
    # option definitions
  };
}

If it doesn't need to declare any options, it can also look like this:

{ ... }: {
  imports = [
    # import paths
  ];

  # option definitions
}

Or, if it doesn't need any imports and takes no arguments, it can even look like this:

{
  # option definitions
}

Import paths can lead to modules themselves, or to directories (in which case the module named default.nix inside that directory is imported).

If the module is a function, it's passed a set with the attributes

• config, the set of all option definitions for the system,
• options, the set of all option declarations for the system,
• pkgs, the set of all packages from <nixpkgs/pkgs>
• lib, the set of utility functions from <nixpkgs/lib>, which are documented in Nixpkgs Manual: 5.1. Nixpkgs Library Functions,
• and modulesPath, the path <nixpkgs/nixos/modules>.

Modules are the building block for configuration in NixOS. Each system's configured state is defined by a set of option definitions.

see also NixOS Manual: 50. Writing NixOS Modules