pyrox.dev
1# Global configuration {#chap-packageconfig}
2
3Nix comes with certain defaults about which packages can and cannot be installed, based on a package's metadata.
4By default, Nix will prevent installation if any of the following criteria are true:
5
6- The package is thought to be broken, and has had its `meta.broken` set to `true`.
7
8- The package isn't intended to run on the given system, as none of its `meta.platforms` match the given system.
9
10- The package's `meta.license` is set to a license which is considered to be unfree.
11
12- The package has known security vulnerabilities but has not or can not be updated for some reason, and a list of issues has been entered into the package's `meta.knownVulnerabilities`.
13
14Each of these criteria can be altered in the Nixpkgs configuration.
15
16:::{.note}
17All this is checked during evaluation already, and the check includes any package that is evaluated.
18In particular, all build-time dependencies are checked.
19:::
20
21A user's Nixpkgs configuration is stored in a user-specific configuration file located at `~/.config/nixpkgs/config.nix`. For example:
22
23```nix
24{ allowUnfree = true; }
25```
26
27:::{.caution}
28Unfree software is not tested or built in Nixpkgs continuous integration, and therefore not cached.
29Most unfree licenses prohibit either executing or distributing the software.
30:::
31
32## Installing broken packages {#sec-allow-broken}
33
34There are several ways to try compiling a package which has been marked as broken.
35
36- For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
37
38 ```ShellSession
39 $ export NIXPKGS_ALLOW_BROKEN=1
40 ```
41
42- For permanently allowing broken packages that match some condition to be built, you may add `allowBrokenPredicate` to your user's configuration file with the desired condition, for example:
43
44 ```nix
45 {
46 allowBrokenPredicate = pkg: builtins.elem (pkgs.lib.getName pkg) [ "hello" ];
47 }
48 ```
49
50- For permanently allowing all broken packages to be built, you may add `allowBroken = true;` to your user's configuration file, like this:
51
52 ```nix
53 { allowBroken = true; }
54 ```
55
56
57## Installing packages on unsupported systems {#sec-allow-unsupported-system}
58
59There are also two ways to try compiling a package which has been marked as unsupported for the given system.
60
61- For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools:
62
63 ```ShellSession
64 $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1
65 ```
66
67- For permanently allowing unsupported packages to be built, you may add `allowUnsupportedSystem = true;` to your user's configuration file, like this:
68
69 ```nix
70 { allowUnsupportedSystem = true; }
71 ```
72
73The difference between a package being unsupported on some system and being broken is admittedly a bit fuzzy. If a program *ought* to work on a certain platform, but doesn't, the platform should be included in `meta.platforms`, but marked as broken with e.g. `meta.broken = !hostPlatform.isWindows`. Of course, this begs the question of what "ought" means exactly. That is left to the package maintainer.
74
75## Installing unfree packages {#sec-allow-unfree}
76
77All users of Nixpkgs are free software users, and many users (and developers) of Nixpkgs want to limit and tightly control their exposure to unfree software.
78At the same time, many users need (or want) to run some specific pieces of proprietary software.
79Nixpkgs includes some expressions for unfree software packages.
80By default unfree software cannot be installed and doesn’t show up in searches.
81
82There are several ways to tweak how Nix handles a package which has been marked as unfree.
83
84- To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools:
85
86 ```ShellSession
87 $ export NIXPKGS_ALLOW_UNFREE=1
88 ```
89
90- It is possible to permanently allow individual unfree packages, while still blocking unfree packages by default using the `allowUnfreePredicate` configuration option in the user configuration file.
91
92 This option is a function which accepts a package as a parameter, and returns a boolean. The following example configuration accepts a package and always returns false:
93
94 ```nix
95 { allowUnfreePredicate = (pkg: false); }
96 ```
97
98 For a more useful example, try the following. This configuration only allows unfree packages named roon-server and Visual Studio Code:
99
100 ```nix
101 {
102 allowUnfreePredicate =
103 pkg:
104 builtins.elem (lib.getName pkg) [
105 "roon-server"
106 "vscode"
107 ];
108 }
109 ```
110
111- It is also possible to allow and block licenses that are specifically acceptable or not acceptable, using `allowlistedLicenses` and `blocklistedLicenses`, respectively.
112
113 The following example configuration allowlists the licenses `amd` and `wtfpl`:
114
115 ```nix
116 {
117 allowlistedLicenses = with lib.licenses; [
118 amd
119 wtfpl
120 ];
121 }
122 ```
123
124 The following example configuration blocklists the `gpl3Only` and `agpl3Only` licenses:
125
126 ```nix
127 {
128 blocklistedLicenses = with lib.licenses; [
129 agpl3Only
130 gpl3Only
131 ];
132 }
133 ```
134
135 Note that `allowlistedLicenses` only applies to unfree licenses unless `allowUnfree` is enabled. It is not a generic allowlist for all types of licenses. `blocklistedLicenses` applies to all licenses.
136
137A complete list of licenses can be found in the file `lib/licenses.nix` of the nixpkgs tree.
138
139## Installing insecure packages {#sec-allow-insecure}
140
141There are several ways to tweak how Nix handles a package which has been marked as insecure.
142
143- To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools:
144
145 ```ShellSession
146 $ export NIXPKGS_ALLOW_INSECURE=1
147 ```
148
149- It is possible to permanently allow individual insecure packages, while still blocking other insecure packages by default using the `permittedInsecurePackages` configuration option in the user configuration file.
150
151 The following example configuration permits the installation of the hypothetically insecure package `hello`, version `1.2.3`:
152
153 ```nix
154 { permittedInsecurePackages = [ "hello-1.2.3" ]; }
155 ```
156
157- It is also possible to create a custom policy around which insecure packages to allow and deny, by overriding the `allowInsecurePredicate` configuration option.
158
159 The `allowInsecurePredicate` option is a function which accepts a package and returns a boolean, much like `allowUnfreePredicate`.
160
161 The following configuration example allows any version of the `ovftool` package:
162
163 ```nix
164 { allowInsecurePredicate = pkg: builtins.elem (lib.getName pkg) [ "ovftool" ]; }
165 ```
166
167 Note that `permittedInsecurePackages` is only checked if `allowInsecurePredicate` is not specified.
168
169## Modify packages via `packageOverrides` {#sec-modify-via-packageOverrides}
170
171You can define a function called `packageOverrides` in your local `~/.config/nixpkgs/config.nix` to override Nix packages. It must be a function that takes pkgs as an argument and returns a modified set of packages.
172
173```nix
174{
175 packageOverrides = pkgs: rec {
176 foo = pkgs.foo.override {
177 # ...
178 };
179 };
180}
181```
182
183## `config` Options Reference {#sec-config-options-reference}
184
185The following attributes can be passed in [`config`](#chap-packageconfig).
186
187```{=include=} options
188id-prefix: opt-
189list-id: configuration-variable-list
190source: ../config-options.json
191```
192
193
194## Declarative Package Management {#sec-declarative-package-management}
195
196### Build an environment {#sec-building-environment}
197
198Using `packageOverrides`, it is possible to manage packages declaratively. This means that we can list all of our desired packages within a declarative Nix expression. For example, to have `aspell`, `bc`, `ffmpeg`, `coreutils`, `gdb`, `nix`, `emscripten`, `jq`, `nox`, and `silver-searcher`, we could use the following in `~/.config/nixpkgs/config.nix`:
199
200```nix
201{
202 packageOverrides =
203 pkgs: with pkgs; {
204 myPackages = pkgs.buildEnv {
205 name = "my-packages";
206 paths = [
207 aspell
208 bc
209 coreutils
210 gdb
211 ffmpeg
212 nix
213 emscripten
214 jq
215 nox
216 silver-searcher
217 ];
218 };
219 };
220}
221```
222
223To install it into our environment, you can just run `nix-env -iA nixpkgs.myPackages`. If you want to load the packages to be built from a working copy of `nixpkgs` you just run `nix-env -f. -iA myPackages`. To explore what's been installed, just look through `~/.nix-profile/`. You can see that a lot of stuff has been installed. Some of this stuff is useful some of it isn't. Let's tell Nixpkgs to only link the stuff that we want:
224
225```nix
226{
227 packageOverrides =
228 pkgs: with pkgs; {
229 myPackages = pkgs.buildEnv {
230 name = "my-packages";
231 paths = [
232 aspell
233 bc
234 coreutils
235 gdb
236 ffmpeg
237 nix
238 emscripten
239 jq
240 nox
241 silver-searcher
242 ];
243 pathsToLink = [
244 "/share"
245 "/bin"
246 ];
247 };
248 };
249}
250```
251
252`pathsToLink` tells Nixpkgs to only link the paths listed which gets rid of the extra stuff in the profile. `/bin` and `/share` are good defaults for a user environment, getting rid of the clutter. If you are running on Nix on macOS, you may want to add another path as well, `/Applications`, that makes GUI apps available.
253
254### Getting documentation {#sec-getting-documentation}
255
256After building that new environment, look through `~/.nix-profile` to make sure everything is there that we wanted. Discerning readers will note that some files are missing. Look inside `~/.nix-profile/share/man/man1/` to verify this. There are no man pages for any of the Nix tools! This is because some packages like Nix have multiple outputs for things like documentation (see section 4). Let's make Nix install those as well.
257
258```nix
259{
260 packageOverrides =
261 pkgs: with pkgs; {
262 myPackages = pkgs.buildEnv {
263 name = "my-packages";
264 paths = [
265 aspell
266 bc
267 coreutils
268 ffmpeg
269 nix
270 emscripten
271 jq
272 nox
273 silver-searcher
274 ];
275 pathsToLink = [
276 "/share/man"
277 "/share/doc"
278 "/bin"
279 ];
280 extraOutputsToInstall = [
281 "man"
282 "doc"
283 ];
284 };
285 };
286}
287```
288
289This provides us with some useful documentation for using our packages. However, if we actually want those manpages to be detected by man, we need to set up our environment. This can also be managed within Nix expressions.
290
291```nix
292{
293 packageOverrides = pkgs: {
294 myProfile = pkgs.writeText "my-profile" ''
295 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
296 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
297 '';
298 myPackages = pkgs.buildEnv {
299 name = "my-packages";
300 paths = with pkgs; [
301 (runCommand "profile" { } ''
302 mkdir -p $out/etc/profile.d
303 cp ${myProfile} $out/etc/profile.d/my-profile.sh
304 '')
305 aspell
306 bc
307 coreutils
308 ffmpeg
309 man
310 nix
311 emscripten
312 jq
313 nox
314 silver-searcher
315 ];
316 pathsToLink = [
317 "/share/man"
318 "/share/doc"
319 "/bin"
320 "/etc"
321 ];
322 extraOutputsToInstall = [
323 "man"
324 "doc"
325 ];
326 };
327 };
328}
329```
330
331For this to work fully, you must also have this script sourced when you are logged in. Try adding something like this to your `~/.profile` file:
332
333```ShellSession
334#!/bin/sh
335if [ -d "${HOME}/.nix-profile/etc/profile.d" ]; then
336 for i in "${HOME}/.nix-profile/etc/profile.d/"*.sh; do
337 if [ -r "$i" ]; then
338 . "$i"
339 fi
340 done
341fi
342```
343
344Now just run `. "${HOME}/.profile"` and you can start loading man pages from your environment.
345
346### GNU info setup {#sec-gnu-info-setup}
347
348Configuring GNU info is a little bit trickier than man pages. To work correctly, info needs a database to be generated. This can be done with some small modifications to our environment scripts.
349
350```nix
351{
352 packageOverrides = pkgs: {
353 myProfile = pkgs.writeText "my-profile" ''
354 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
355 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
356 export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
357 '';
358 myPackages = pkgs.buildEnv {
359 name = "my-packages";
360 paths = with pkgs; [
361 (runCommand "profile" { } ''
362 mkdir -p $out/etc/profile.d
363 cp ${myProfile} $out/etc/profile.d/my-profile.sh
364 '')
365 aspell
366 bc
367 coreutils
368 ffmpeg
369 man
370 nix
371 emscripten
372 jq
373 nox
374 silver-searcher
375 texinfoInteractive
376 ];
377 pathsToLink = [
378 "/share/man"
379 "/share/doc"
380 "/share/info"
381 "/bin"
382 "/etc"
383 ];
384 extraOutputsToInstall = [
385 "man"
386 "doc"
387 "info"
388 ];
389 postBuild = ''
390 if [ -x $out/bin/install-info -a -w $out/share/info ]; then
391 shopt -s nullglob
392 for i in $out/share/info/*.info $out/share/info/*.info.gz; do
393 $out/bin/install-info $i $out/share/info/dir
394 done
395 fi
396 '';
397 };
398 };
399}
400```
401
402`postBuild` tells Nixpkgs to run a command after building the environment. In this case, `install-info` adds the installed info pages to `dir` which is GNU info's default root node. Note that `texinfoInteractive` is added to the environment to give the `install-info` command.