NixOS modules - Revision history

Blokyk: Add a "Disabling modules" section in advanced usages, partially migrated from the unofficial wiki

2026-03-16T03:39:45Z

Add a "Disabling modules" section in advanced usages, partially migrated from the unofficial wiki

@@ Line 374: / Line 374: @@
 * [https://gitlab.com/simple-nixos-mailserver/nixos-mailserver nixos-mailserver] - full-featured mail server module
 * [https://github.com/xtruder/nix-profiles X-Truder Nix-profiles] - modules for Nix to quickly configure your system based on application profiles.
 == Under the hood  ==

Dafitt: Added a short meta.doc description to the example

2026-02-09T10:32:50Z

Added a short meta.doc description to the example

← Older revision		Revision as of 10:32, 9 February 2026
Line 276:		Line 276:
	To see how modules are setup and reuse other modules in practice put <code>hello.nix</code> in the same folder as your <code>configuration.nix</code>:		To see how modules are setup and reuse other modules in practice put <code>hello.nix</code> in the same folder as your <code>configuration.nix</code>:

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">{ lib, pkgs, config, ... }:
	{ lib, pkgs, config, ... }:
	with lib;		with lib;
	let		let
Line 285:		Line 284:
	cfg = config.services.hello;		cfg = config.services.hello;
	in {		in {
			meta.doc = "Says hello every time you login.";

	# Declare what settings a user of this "hello.nix" module CAN SET.		# Declare what settings a user of this "hello.nix" module CAN SET.
	options.services.hello = {		options.services.hello = {
Line 303:		Line 304:
	};		};
	};		};
	}		}</syntaxhighlight>
	</syntaxhighlight>

	The other <code>configuration.nix</code> module can then import this <code>hello.nix</code> module		The other <code>configuration.nix</code> module can then import this <code>hello.nix</code> module

Dafitt: Changed example type

2026-02-09T10:11:42Z

Changed example type

← Older revision		Revision as of 10:11, 9 February 2026
Line 216:		Line 216:

	settings = lib.options.mkOption {		settings = lib.options.mkOption {
	type = lib.types.~~json~~;		type = lib.types.toml;
	default = {};		default = {};
	description = ''		description = ''

Dafitt: /* Structure */ Added meta block.

2026-02-09T10:04:04Z

Structure: Added meta block.

← Older revision		Revision as of 10:04, 9 February 2026
Line 26:		Line 26:
	# using the "option" above.		# using the "option" above.
	# Options for modules imported in "imports" can be set here.		# Options for modules imported in "imports" can be set here.
			};

			meta = {
			# Meta-attributes to provide extra information like documentation or maintainers.
	};		};
	}		}

Dafitt: Added an example to Option Declarations

2026-02-09T09:59:02Z

Added an example to Option Declarations

← Older revision		Revision as of 09:59, 9 February 2026
Line 194:		Line 194:
	package = lib.options.mkPackageOption pkgs "bash" { };		package = lib.options.mkPackageOption pkgs "bash" { };
	# type = lib.types.package;		# type = lib.types.package;

			numberOfTheDay = lib.options.mkOption {
			type = lib.types.ints.between 50 100;
			default = 61;
			};

	groceries = lib.options.mkOption {		groceries = lib.options.mkOption {

Dafitt: Added example example

2026-02-09T09:50:00Z

Added example example

← Older revision		Revision as of 09:50, 9 February 2026
Line 253:		Line 253:
	"unit1" = { unit = "m" };		"unit1" = { unit = "m" };
	"unit2".unit = "cm";		"unit2".unit = "cm";
			"unit3" = {}; # kg
	};		};
	};		};

Dafitt: Removed redundant outdated text, that is linked to the manual. Also improved wording in the section.

2026-02-09T09:47:37Z

Removed redundant outdated text, that is linked to the manual. Also improved wording in the section.

← Older revision		Revision as of 09:47, 9 February 2026
Line 170:		Line 170:
	Imports are paths to other NixOS modules that should be included in the evaluation of the system configuration. A default set of modules is defined in {{Nixpkgs Link\|nixos/modules/module-list.nix}}. These don't need to be added in the import list.		Imports are paths to other NixOS modules that should be included in the evaluation of the system configuration. A default set of modules is defined in {{Nixpkgs Link\|nixos/modules/module-list.nix}}. These don't need to be added in the import list.

	=== Declarations ===		=== Option Declarations ===

	Declarations specify a module's external interfaces.		Declarations specify a module's external interfaces.
Line 176:		Line 176:
	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
	options = {		options = {
	optionName = mkOption {		optionName = lib.options.mkOption {
	# ...		# ...
	};		};
Line 182:		Line 182:
	</syntaxhighlight>		</syntaxhighlight>

	They are created with {{ic\|mkOption}}, a function ~~accepting a set with following attributes:~~<ref>{{Nixpkgs Link\|lib/options.nix#L66-L88}}</ref><ref>{{manual:nixos\|sec=#sec-option-declarations\|chapter=42.1. Option Declarations}}</ref>		They are created with {{ic\|mkOption}}, a function in <code>lib</code>.<ref>{{Nixpkgs Link\|lib/options.nix#L66-L88}}</ref><ref>{{manual:nixos\|sec=#sec-option-declarations\|chapter=42.1. Option Declarations}}</ref>

	~~<dl>~~
	~~<dt><code>type</code></dt>~~
	~~<dd><p>~~
	~~The type of the option. It may~~
	~~be omitted, but that’s not advisable since it may lead to errors that~~
	~~are hard to diagnose.~~
	~~</p></dd>~~
	~~<dt><code>default</code></dt>~~
	~~<dd><p>~~
	~~The default value used if no value is defined by any module. A default is~~
	~~not required; but if a default is not given, then users of the module~~
	~~will have to define the value of the option, otherwise an error will be~~
	~~thrown.~~
	~~</p></dd>~~
	~~<dt><code class="varname">example</code></dt>~~
	~~<dd><p>~~
	~~An example value that will be shown in the NixOS manual.~~
	~~</p></dd>~~
	~~<dt><code>description</code></dt>~~
	~~<dd><p>~~
	~~A textual description of the option, in DocBook format, that will be~~
	~~included in the NixOS manual.~~
	~~</p></dd>~~
	~~</dl~~>

	==== Examples ====		==== Examples ====
	[[File:NixOS Search - Options.png\|alt=A search query `programs.bat.` on the official NixOS Search - Options.\|thumb\|~~268x268px~~\|For more examples you can browse [https://github.com/NixOS/nixpkgs NixOS/nixpkgs]: Search a similar option on [https://search.nixos.org/options NixOS Search - Options] and click on the link beside "Declared in".]]		[[File:NixOS Search - Options.png\|alt=A search query `programs.bat.` on the official NixOS Search - Options.\|thumb\|270x270px\|For even more examples you can browse [https://github.com/NixOS/nixpkgs NixOS/nixpkgs]: Search a similar option on [https://search.nixos.org/options NixOS Search - Options] and click on the link beside "Declared in" and studding the option declarations.]]
	Some useful option examples.<syntaxhighlight lang="nixos">		Some useful option examples:<syntaxhighlight lang="nixos">
	{ lib, pkgs, ... }: {		{ lib, pkgs, ... }: {
	options.examples = {		options.examples = {
Line 235:		Line 210:
	default = {};		default = {};
	description = ''		description = ''
	Showcase the possible option for settings of a configuration file.		Showcase the possible option for settings of a configuration
			file.
	Always document, where you can find possible options e.g.:		Always document, where you can find possible options e.g.:
	Refer <https://example.com/> for possible options.		Refer <https://example.com/> for possible options.

Dafitt: Added examples to Declarations

2026-02-09T09:31:55Z

Added examples to Declarations

@@ Line 174: / Line 174: @@
 Declarations specify a module's external interfaces.
-<syntaxhighlight lang=nix>
+<syntaxhighlight lang="nix">
-optionName = mkOption {
+options = {
-  # ...
+  optionName = mkOption {
+}
 </syntaxhighlight>
@@ Line 207: / Line 209: @@
 </dl>
 == Rationale ==

Qyriad: /* With Flakes */ fix? typo and typesetting; idk what {{|c|nixos-rebuild}} was intended to be

2025-07-29T18:02:49Z

With Flakes: fix? typo and typesetting; idk what {{|c|nixos-rebuild}} was intended to be

← Older revision		Revision as of 18:02, 29 July 2025
Line 409:		Line 409:
	If you want to develop a module from a git repo, you can use `--override-input`. For example, if you have an input in your flake called {{ic\|jovian}},, you can use		If you want to develop a module from a git repo, you can use `--override-input`. For example, if you have an input in your flake called {{ic\|jovian}},, you can use
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	nixos-rebuild switch --override-input jovian <path-to-url>` --flake <uri>		nixos-rebuild switch --override-input jovian <path-to-url> --flake <uri>
	</syntaxhighlight>		</syntaxhighlight>
	Of course, it doesn't have to ~~be {{\|c~~\|nixos-rebuild}} in particular.		Of course, it doesn't have to [[nixos-rebuild\|<code>nixos-rebuild</code>]] in particular.

	== References ==		== References ==

Qyriad: /* Under the hood */ fix typesetting for inline code

2025-07-29T17:56:29Z

Under the hood: fix typesetting for inline code

← Older revision		Revision as of 17:56, 29 July 2025
Line 360:		Line 360:
	The module system itself is rather complex, but here's a short overview. A module evaluation consists of a set of "modules", which can do three things:		The module system itself is rather complex, but here's a short overview. A module evaluation consists of a set of "modules", which can do three things:

	* Import other modules (through imports = [ ./other-module.nix ])		* Import other modules (through <code>imports = [ ./other-module.nix ]</code>)
	* Declare options (through options = { ... })		* Declare options (through <code>options = { ... }</code>)
	* Define option values (through \|config = { ... }, or without the config key as a shorthand if you don't have imports or options)		* Define option values (through <code>config = { ... }</code>, or without the config key as a shorthand if you don't have imports or options)

	To do the actual evaluation, there's these rough steps:		To do the actual evaluation, there's these rough steps: