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 = pkg: builtins.elem (lib.getName pkg) [
103 "roon-server"
104 "vscode"
105 ];
106 }
107 ```
108
109- It is also possible to allow and block licenses that are specifically acceptable or not acceptable, using `allowlistedLicenses` and `blocklistedLicenses`, respectively.
110
111 The following example configuration allowlists the licenses `amd` and `wtfpl`:
112
113 ```nix
114 {
115 allowlistedLicenses = with lib.licenses; [ amd wtfpl ];
116 }
117 ```
118
119 The following example configuration blocklists the `gpl3Only` and `agpl3Only` licenses:
120
121 ```nix
122 {
123 blocklistedLicenses = with lib.licenses; [ agpl3Only gpl3Only ];
124 }
125 ```
126
127 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.
128
129A complete list of licenses can be found in the file `lib/licenses.nix` of the nixpkgs tree.
130
131## Installing insecure packages {#sec-allow-insecure}
132
133There are several ways to tweak how Nix handles a package which has been marked as insecure.
134
135- To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools:
136
137 ```ShellSession
138 $ export NIXPKGS_ALLOW_INSECURE=1
139 ```
140
141- 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.
142
143 The following example configuration permits the installation of the hypothetically insecure package `hello`, version `1.2.3`:
144
145 ```nix
146 {
147 permittedInsecurePackages = [
148 "hello-1.2.3"
149 ];
150 }
151 ```
152
153- It is also possible to create a custom policy around which insecure packages to allow and deny, by overriding the `allowInsecurePredicate` configuration option.
154
155 The `allowInsecurePredicate` option is a function which accepts a package and returns a boolean, much like `allowUnfreePredicate`.
156
157 The following configuration example only allows insecure packages with very short names:
158
159 ```nix
160 {
161 allowInsecurePredicate = pkg: builtins.stringLength (lib.getName pkg) <= 5;
162 }
163 ```
164
165 Note that `permittedInsecurePackages` is only checked if `allowInsecurePredicate` is not specified.
166
167## Modify packages via `packageOverrides` {#sec-modify-via-packageOverrides}
168
169You 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.
170
171```nix
172{
173 packageOverrides = pkgs: rec {
174 foo = pkgs.foo.override { /* ... */ };
175 };
176}
177```
178
179## `config` Options Reference {#sec-config-options-reference}
180
181The following attributes can be passed in [`config`](#chap-packageconfig).
182
183```{=include=} options
184id-prefix: opt-
185list-id: configuration-variable-list
186source: ../config-options.json
187```
188
189
190## Declarative Package Management {#sec-declarative-package-management}
191
192### Build an environment {#sec-building-environment}
193
194Using `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`, `nixUnstable`, `emscripten`, `jq`, `nox`, and `silver-searcher`, we could use the following in `~/.config/nixpkgs/config.nix`:
195
196```nix
197{
198 packageOverrides = pkgs: with pkgs; {
199 myPackages = pkgs.buildEnv {
200 name = "my-packages";
201 paths = [
202 aspell
203 bc
204 coreutils
205 gdb
206 ffmpeg
207 nixUnstable
208 emscripten
209 jq
210 nox
211 silver-searcher
212 ];
213 };
214 };
215}
216```
217
218To 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:
219
220```nix
221{
222 packageOverrides = pkgs: with pkgs; {
223 myPackages = pkgs.buildEnv {
224 name = "my-packages";
225 paths = [
226 aspell
227 bc
228 coreutils
229 gdb
230 ffmpeg
231 nixUnstable
232 emscripten
233 jq
234 nox
235 silver-searcher
236 ];
237 pathsToLink = [ "/share" "/bin" ];
238 };
239 };
240}
241```
242
243`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.
244
245### Getting documentation {#sec-getting-documentation}
246
247After 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.
248
249```nix
250{
251 packageOverrides = pkgs: with pkgs; {
252 myPackages = pkgs.buildEnv {
253 name = "my-packages";
254 paths = [
255 aspell
256 bc
257 coreutils
258 ffmpeg
259 nixUnstable
260 emscripten
261 jq
262 nox
263 silver-searcher
264 ];
265 pathsToLink = [ "/share/man" "/share/doc" "/bin" ];
266 extraOutputsToInstall = [ "man" "doc" ];
267 };
268 };
269}
270```
271
272This 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.
273
274```nix
275{
276 packageOverrides = pkgs: with pkgs; rec {
277 myProfile = writeText "my-profile" ''
278 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
279 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
280 '';
281 myPackages = pkgs.buildEnv {
282 name = "my-packages";
283 paths = [
284 (runCommand "profile" {} ''
285 mkdir -p $out/etc/profile.d
286 cp ${myProfile} $out/etc/profile.d/my-profile.sh
287 '')
288 aspell
289 bc
290 coreutils
291 ffmpeg
292 man
293 nixUnstable
294 emscripten
295 jq
296 nox
297 silver-searcher
298 ];
299 pathsToLink = [ "/share/man" "/share/doc" "/bin" "/etc" ];
300 extraOutputsToInstall = [ "man" "doc" ];
301 };
302 };
303}
304```
305
306For 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:
307
308```ShellSession
309#!/bin/sh
310if [ -d "${HOME}/.nix-profile/etc/profile.d" ]; then
311 for i in "${HOME}/.nix-profile/etc/profile.d/"*.sh; do
312 if [ -r "$i" ]; then
313 . "$i"
314 fi
315 done
316fi
317```
318
319Now just run `. "${HOME}/.profile"` and you can start loading man pages from your environment.
320
321### GNU info setup {#sec-gnu-info-setup}
322
323Configuring 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.
324
325```nix
326{
327 packageOverrides = pkgs: with pkgs; rec {
328 myProfile = writeText "my-profile" ''
329 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
330 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
331 export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
332 '';
333 myPackages = pkgs.buildEnv {
334 name = "my-packages";
335 paths = [
336 (runCommand "profile" {} ''
337 mkdir -p $out/etc/profile.d
338 cp ${myProfile} $out/etc/profile.d/my-profile.sh
339 '')
340 aspell
341 bc
342 coreutils
343 ffmpeg
344 man
345 nixUnstable
346 emscripten
347 jq
348 nox
349 silver-searcher
350 texinfoInteractive
351 ];
352 pathsToLink = [ "/share/man" "/share/doc" "/share/info" "/bin" "/etc" ];
353 extraOutputsToInstall = [ "man" "doc" "info" ];
354 postBuild = ''
355 if [ -x $out/bin/install-info -a -w $out/share/info ]; then
356 shopt -s nullglob
357 for i in $out/share/info/*.info $out/share/info/*.info.gz; do
358 $out/bin/install-info $i $out/share/info/dir
359 done
360 fi
361 '';
362 };
363 };
364}
365```
366
367`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.