pyrox.dev
1# NixOS Configuration File {#sec-configuration-file}
2
3The NixOS configuration file generally looks like this:
4
5```nix
6{ config, pkgs, ... }:
7
8{
9 # option definitions
10}
11```
12
13The first line (`{ config, pkgs, ... }:`) denotes that this is actually
14a function that takes at least the two arguments `config` and `pkgs`.
15(These are explained later, in chapter [](#sec-writing-modules)) The
16function returns a *set* of option definitions (`{ ... }`).
17These definitions have the form `name = value`, where `name` is the
18name of an option and `value` is its value. For example,
19
20```nix
21{ config, pkgs, ... }:
22
23{
24 services.httpd.enable = true;
25 services.httpd.adminAddr = "alice@example.org";
26 services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
27}
28```
29
30defines a configuration with three option definitions that together
31enable the Apache HTTP Server with `/webroot` as the document root.
32
33Sets can be nested, and in fact dots in option names are shorthand for
34defining a set containing another set. For instance,
35[](#opt-services.httpd.enable) defines a set named
36`services` that contains a set named `httpd`, which in turn contains an
37option definition named `enable` with value `true`. This means that the
38example above can also be written as:
39
40```nix
41{ config, pkgs, ... }:
42
43{
44 services = {
45 httpd = {
46 enable = true;
47 adminAddr = "alice@example.org";
48 virtualHosts = {
49 localhost = {
50 documentRoot = "/webroot";
51 };
52 };
53 };
54 };
55}
56```
57
58which may be more convenient if you have lots of option definitions that
59share the same prefix (such as `services.httpd`).
60
61NixOS checks your option definitions for correctness. For instance, if
62you try to define an option that doesn't exist (that is, doesn't have a
63corresponding *option declaration*), `nixos-rebuild` will give an error
64like:
65
66```plain
67The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
68```
69
70Likewise, values in option definitions must have a correct type. For
71instance, `services.httpd.enable` must be a Boolean (`true` or `false`).
72Trying to give it a value of another type, such as a string, will cause
73an error:
74
75```plain
76The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
77```
78
79Options have various types of values. The most important are:
80
81Strings
82
83: Strings are enclosed in double quotes, e.g.
84
85 ```nix
86 {
87 networking.hostName = "dexter";
88 }
89 ```
90
91 Special characters can be escaped by prefixing them with a backslash
92 (e.g. `\"`).
93
94 Multi-line strings can be enclosed in *double single quotes*, e.g.
95
96 ```nix
97 {
98 networking.extraHosts =
99 ''
100 127.0.0.2 other-localhost
101 10.0.0.1 server
102 '';
103 }
104 ```
105
106 The main difference is that it strips from each line a number of
107 spaces equal to the minimal indentation of the string as a whole
108 (disregarding the indentation of empty lines), and that characters
109 like `"` and `\` are not special (making it more convenient for
110 including things like shell code). See more info about this in the
111 Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
112
113Booleans
114
115: These can be `true` or `false`, e.g.
116
117 ```nix
118 {
119 networking.firewall.enable = true;
120 networking.firewall.allowPing = false;
121 }
122 ```
123
124Integers
125
126: For example,
127
128 ```nix
129 {
130 boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
131 }
132 ```
133
134 (Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
135 enclosed in quotes to prevent it from being interpreted as a set
136 named `net` containing a set named `ipv4`, and so on. This is
137 because it's not a NixOS option but the literal name of a Linux
138 kernel setting.)
139
140Sets
141
142: Sets were introduced above. They are name/value pairs enclosed in
143 braces, as in the option definition
144
145 ```nix
146 {
147 fileSystems."/boot" =
148 { device = "/dev/sda1";
149 fsType = "ext4";
150 options = [ "rw" "data=ordered" "relatime" ];
151 };
152 }
153 ```
154
155Lists
156
157: The important thing to note about lists is that list elements are
158 separated by whitespace, like this:
159
160 ```nix
161 {
162 boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
163 }
164 ```
165
166 List elements can be any other type, e.g. sets:
167
168 ```nix
169 {
170 swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
171 }
172 ```
173
174Packages
175
176: Usually, the packages you need are already part of the Nix Packages
177 collection, which is a set that can be accessed through the function
178 argument `pkgs`. Typical uses:
179
180 ```nix
181 {
182 environment.systemPackages =
183 [ pkgs.thunderbird
184 pkgs.emacs
185 ];
186
187 services.postgresql.package = pkgs.postgresql_14;
188 }
189 ```
190
191 The latter option definition changes the default PostgreSQL package
192 used by NixOS's PostgreSQL service to 14.x. For more information on
193 packages, including how to add new ones, see
194 [](#sec-custom-packages).