The module system is a language for handling configuration, implemented as a Nix library.
Compared to plain Nix, it adds documentation, type checking and composition or extensibility.
This chapter is new and not complete yet. For a gentle introduction to the module system, in the context of NixOS, see Writing NixOS Modules in the NixOS manual.
Evaluate a set of modules. This function is typically only used once per application (e.g. once in NixOS, once in Home Manager, ...).
A list of modules. These are merged together to form the final configuration.
An attribute set of module arguments that can be used in
This is in contrast to
config._module.args, which is only available after all
imports have been resolved.
class attribute is set and non-
null, the module system will reject
imports with a different
class value should be a string in lower camel case.
If applicable, the
class should match the "prefix" of the attributes used in (experimental) flakes. Some examples are:
nixosTest: modules that constitute a NixOS VM test
A list of strings representing the location at or below which all options are evaluated. This is used by
types.submodule to improve error reporting and find the implicit
name module argument.
The result is an attribute set with the following attributes:
The nested attribute set of all option declarations.
The nested attribute set of all option values.
A module system type. This type is an instance of
types.submoduleWith containing the current
The option definitions that are typed with this type will extend the current set of modules, like
However, the value returned from the type is just the
config, like any submodule.
If you're familiar with prototype inheritance, you can think of this
evalModules invocation as the prototype, and usages of this type as the instances.
This type is also available to the
modules as the module argument
A function similar to
evalModules but building on top of the already passed
modules. Its arguments,
specialArgs are added to the existing values.
If you're familiar with prototype inheritance, you can think of the current, actual
evalModules invocation as the prototype, and the return value of
extendModules as the instance.
This functionality is also available to modules as the
extendModules module argument.
extendModules returns a configuration that shares very little with the original
evalModules invocation, because the module arguments may be different.
So if you have a configuration that has been (or will be) largely evaluated, almost none of the computation is shared with the configuration returned by
The real work of module evaluation happens while computing the values in
options, so multiple invocations of
extendModules have a particularly small cost, as long as only the final
options are evaluated.
If you do reference multiple
options) from before and after
extendModules, evaluation performance is the same as with multiple
evalModules invocations, because the new modules' ability to override existing configuration fundamentally requires constructing a new
A portion of the configuration tree which is elided from
A nominal type marker, always