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 in to 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{
25 allowUnfree = true;
26}
27```
28
29:::{.caution}
30Unfree software is not tested or built in Nixpkgs continuous integration, and therefore not cached.
31Most unfree licenses prohibit either executing or distributing the software.
32:::
33
34## Installing broken packages {#sec-allow-broken}
35
36There are two ways to try compiling a package which has been marked as broken.
37
38- For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
39
40 ```ShellSession
41 $ export NIXPKGS_ALLOW_BROKEN=1
42 ```
43
44- For permanently allowing broken packages to be built, you may add `allowBroken = true;` to your user's configuration file, like this:
45
46 ```nix
47 {
48 allowBroken = true;
49 }
50 ```
51
52
53## Installing packages on unsupported systems {#sec-allow-unsupported-system}
54
55There are also two ways to try compiling a package which has been marked as unsupported for the given system.
56
57- For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools:
58
59 ```ShellSession
60 $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1
61 ```
62
63- For permanently allowing unsupported packages to be built, you may add `allowUnsupportedSystem = true;` to your user's configuration file, like this:
64
65 ```nix
66 {
67 allowUnsupportedSystem = true;
68 }
69 ```
70
71The 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.
72
73## Installing unfree packages {#sec-allow-unfree}
74
75All 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.
76At the same time, many users need (or want) to run some specific pieces of proprietary software.
77Nixpkgs includes some expressions for unfree software packages.
78By default unfree software cannot be installed and doesn’t show up in searches.
79
80There are several ways to tweak how Nix handles a package which has been marked as unfree.
81
82- To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools:
83
84 ```ShellSession
85 $ export NIXPKGS_ALLOW_UNFREE=1
86 ```
87
88- 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.
89
90 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:
91
92 ```nix
93 {
94 allowUnfreePredicate = (pkg: false);
95 }
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 {
155 permittedInsecurePackages = [
156 "hello-1.2.3"
157 ];
158 }
159 ```
160
161- It is also possible to create a custom policy around which insecure packages to allow and deny, by overriding the `allowInsecurePredicate` configuration option.
162
163 The `allowInsecurePredicate` option is a function which accepts a package and returns a boolean, much like `allowUnfreePredicate`.
164
165 The following configuration example allows any version of the `ovftool` package:
166
167 ```nix
168 {
169 allowInsecurePredicate =
170 pkg:
171 builtins.elem (lib.getName pkg) [
172 "ovftool"
173 ];
174 }
175 ```
176
177 Note that `permittedInsecurePackages` is only checked if `allowInsecurePredicate` is not specified.
178
179## Modify packages via `packageOverrides` {#sec-modify-via-packageOverrides}
180
181You 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.
182
183```nix
184{
185 packageOverrides = pkgs: rec {
186 foo = pkgs.foo.override {
187 # ...
188 };
189 };
190}
191```
192
193## `config` Options Reference {#sec-config-options-reference}
194
195The following attributes can be passed in [`config`](#chap-packageconfig).
196
197```{=include=} options
198id-prefix: opt-
199list-id: configuration-variable-list
200source: ../config-options.json
201```
202
203
204## Declarative Package Management {#sec-declarative-package-management}
205
206### Build an environment {#sec-building-environment}
207
208Using `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`:
209
210```nix
211{
212 packageOverrides =
213 pkgs: with pkgs; {
214 myPackages = pkgs.buildEnv {
215 name = "my-packages";
216 paths = [
217 aspell
218 bc
219 coreutils
220 gdb
221 ffmpeg
222 nix
223 emscripten
224 jq
225 nox
226 silver-searcher
227 ];
228 };
229 };
230}
231```
232
233To 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:
234
235```nix
236{
237 packageOverrides =
238 pkgs: with pkgs; {
239 myPackages = pkgs.buildEnv {
240 name = "my-packages";
241 paths = [
242 aspell
243 bc
244 coreutils
245 gdb
246 ffmpeg
247 nix
248 emscripten
249 jq
250 nox
251 silver-searcher
252 ];
253 pathsToLink = [
254 "/share"
255 "/bin"
256 ];
257 };
258 };
259}
260```
261
262`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.
263
264### Getting documentation {#sec-getting-documentation}
265
266After 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.
267
268```nix
269{
270 packageOverrides =
271 pkgs: with pkgs; {
272 myPackages = pkgs.buildEnv {
273 name = "my-packages";
274 paths = [
275 aspell
276 bc
277 coreutils
278 ffmpeg
279 nix
280 emscripten
281 jq
282 nox
283 silver-searcher
284 ];
285 pathsToLink = [
286 "/share/man"
287 "/share/doc"
288 "/bin"
289 ];
290 extraOutputsToInstall = [
291 "man"
292 "doc"
293 ];
294 };
295 };
296}
297```
298
299This 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.
300
301```nix
302{
303 packageOverrides = pkgs: {
304 myProfile = pkgs.writeText "my-profile" ''
305 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
306 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
307 '';
308 myPackages = pkgs.buildEnv {
309 name = "my-packages";
310 paths = with pkgs; [
311 (runCommand "profile" { } ''
312 mkdir -p $out/etc/profile.d
313 cp ${myProfile} $out/etc/profile.d/my-profile.sh
314 '')
315 aspell
316 bc
317 coreutils
318 ffmpeg
319 man
320 nix
321 emscripten
322 jq
323 nox
324 silver-searcher
325 ];
326 pathsToLink = [
327 "/share/man"
328 "/share/doc"
329 "/bin"
330 "/etc"
331 ];
332 extraOutputsToInstall = [
333 "man"
334 "doc"
335 ];
336 };
337 };
338}
339```
340
341For 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:
342
343```ShellSession
344#!/bin/sh
345if [ -d "${HOME}/.nix-profile/etc/profile.d" ]; then
346 for i in "${HOME}/.nix-profile/etc/profile.d/"*.sh; do
347 if [ -r "$i" ]; then
348 . "$i"
349 fi
350 done
351fi
352```
353
354Now just run `. "${HOME}/.profile"` and you can start loading man pages from your environment.
355
356### GNU info setup {#sec-gnu-info-setup}
357
358Configuring 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.
359
360```nix
361{
362 packageOverrides = pkgs: {
363 myProfile = pkgs.writeText "my-profile" ''
364 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
365 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
366 export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
367 '';
368 myPackages = pkgs.buildEnv {
369 name = "my-packages";
370 paths = with pkgs; [
371 (runCommand "profile" { } ''
372 mkdir -p $out/etc/profile.d
373 cp ${myProfile} $out/etc/profile.d/my-profile.sh
374 '')
375 aspell
376 bc
377 coreutils
378 ffmpeg
379 man
380 nix
381 emscripten
382 jq
383 nox
384 silver-searcher
385 texinfoInteractive
386 ];
387 pathsToLink = [
388 "/share/man"
389 "/share/doc"
390 "/share/info"
391 "/bin"
392 "/etc"
393 ];
394 extraOutputsToInstall = [
395 "man"
396 "doc"
397 "info"
398 ];
399 postBuild = ''
400 if [ -x $out/bin/install-info -a -w $out/share/info ]; then
401 shopt -s nullglob
402 for i in $out/share/info/*.info $out/share/info/*.info.gz; do
403 $out/bin/install-info $i $out/share/info/dir
404 done
405 fi
406 '';
407 };
408 };
409}
410```
411
412`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.