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 networking.hostName = "dexter";
84 ```
85
86 Special characters can be escaped by prefixing them with a backslash
87 (e.g. `\"`).
88
89 Multi-line strings can be enclosed in *double single quotes*, e.g.
90
91 ```nix
92 networking.extraHosts =
93 ''
94 127.0.0.2 other-localhost
95 10.0.0.1 server
96 '';
97 ```
98
99 The main difference is that it strips from each line a number of
100 spaces equal to the minimal indentation of the string as a whole
101 (disregarding the indentation of empty lines), and that characters
102 like `"` and `\` are not special (making it more convenient for
103 including things like shell code). See more info about this in the
104 Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
105
106Booleans
107
108: These can be `true` or `false`, e.g.
109
110 ```nix
111 networking.firewall.enable = true;
112 networking.firewall.allowPing = false;
113 ```
114
115Integers
116
117: For example,
118
119 ```nix
120 boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
121 ```
122
123 (Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
124 enclosed in quotes to prevent it from being interpreted as a set
125 named `net` containing a set named `ipv4`, and so on. This is
126 because it's not a NixOS option but the literal name of a Linux
127 kernel setting.)
128
129Sets
130
131: Sets were introduced above. They are name/value pairs enclosed in
132 braces, as in the option definition
133
134 ```nix
135 fileSystems."/boot" =
136 { device = "/dev/sda1";
137 fsType = "ext4";
138 options = [ "rw" "data=ordered" "relatime" ];
139 };
140 ```
141
142Lists
143
144: The important thing to note about lists is that list elements are
145 separated by whitespace, like this:
146
147 ```nix
148 boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
149 ```
150
151 List elements can be any other type, e.g. sets:
152
153 ```nix
154 swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
155 ```
156
157Packages
158
159: Usually, the packages you need are already part of the Nix Packages
160 collection, which is a set that can be accessed through the function
161 argument `pkgs`. Typical uses:
162
163 ```nix
164 environment.systemPackages =
165 [ pkgs.thunderbird
166 pkgs.emacs
167 ];
168
169 services.postgresql.package = pkgs.postgresql_14;
170 ```
171
172 The latter option definition changes the default PostgreSQL package
173 used by NixOS's PostgreSQL service to 10.x. For more information on
174 packages, including how to add new ones, see
175 [](#sec-custom-packages).