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