pyrox.dev
1# Global configuration {#chap-packageconfig}
2
3Nix comes with certain defaults about what packages can and cannot be installed, based on a package's metadata. By default, Nix will prevent installation if any of the following criteria are true:
4
5- The package is thought to be broken, and has had its `meta.broken` set to `true`.
6
7- The package isn't intended to run on the given system, as none of its `meta.platforms` match the given system.
8
9- The package's `meta.license` is set to a license which is considered to be unfree.
10
11- 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`.
12
13Note that all this is checked during evaluation already, and the check includes any package that is evaluated. In particular, all build-time dependencies are checked. `nix-env -qa` will (attempt to) hide any packages that would be refused.
14
15Each of these criteria can be altered in the nixpkgs configuration.
16
17The nixpkgs configuration for a NixOS system is set in the `configuration.nix`, as in the following example:
18
19```nix
20{
21 nixpkgs.config = {
22 allowUnfree = true;
23 };
24}
25```
26
27However, this does not allow unfree software for individual users. Their configurations are managed separately.
28
29A user's nixpkgs configuration is stored in a user-specific configuration file located at `~/.config/nixpkgs/config.nix`. For example:
30
31```nix
32{
33 allowUnfree = true;
34}
35```
36
37Note that we are not able to test or build unfree software on Hydra due to policy. Most unfree licenses prohibit us from either executing or distributing the software.
38
39## Installing broken packages {#sec-allow-broken}
40
41There are two ways to try compiling a package which has been marked as broken.
42
43- For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
44
45 ```ShellSession
46 $ export NIXPKGS_ALLOW_BROKEN=1
47 ```
48
49- For permanently allowing broken packages to be built, you may add `allowBroken = true;` to your user's configuration file, like this:
50
51 ```nix
52 {
53 allowBroken = true;
54 }
55 ```
56
57
58## Installing packages on unsupported systems {#sec-allow-unsupported-system}
59
60There are also two ways to try compiling a package which has been marked as unsupported for the given system.
61
62- For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools:
63
64 ```ShellSession
65 $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1
66 ```
67
68- For permanently allowing unsupported packages to be built, you may add `allowUnsupportedSystem = true;` to your user's configuration file, like this:
69
70 ```nix
71 {
72 allowUnsupportedSystem = true;
73 }
74 ```
75
76The 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.
77
78## Installing unfree packages {#sec-allow-unfree}
79
80All 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.
81At the same time, many users need (or want) to run some specific pieces of proprietary software.
82Nixpkgs includes some expressions for unfree software packages.
83By default unfree software cannot be installed and doesn’t show up in searches.
84
85There are several ways to tweak how Nix handles a package which has been marked as unfree.
86
87- To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools:
88
89 ```ShellSession
90 $ export NIXPKGS_ALLOW_UNFREE=1
91 ```
92
93- 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.
94
95 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:
96
97 ```nix
98 {
99 allowUnfreePredicate = (pkg: false);
100 }
101 ```
102
103 For a more useful example, try the following. This configuration only allows unfree packages named roon-server and visual studio code:
104
105 ```nix
106 {
107 allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [
108 "roon-server"
109 "vscode"
110 ];
111 }
112 ```
113
114- It is also possible to allow and block licenses that are specifically acceptable or not acceptable, using `allowlistedLicenses` and `blocklistedLicenses`, respectively.
115
116 The following example configuration allowlists the licenses `amd` and `wtfpl`:
117
118 ```nix
119 {
120 allowlistedLicenses = with lib.licenses; [ amd wtfpl ];
121 }
122 ```
123
124 The following example configuration blocklists the `gpl3Only` and `agpl3Only` licenses:
125
126 ```nix
127 {
128 blocklistedLicenses = with lib.licenses; [ agpl3Only gpl3Only ];
129 }
130 ```
131
132 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.
133
134A complete list of licenses can be found in the file `lib/licenses.nix` of the nixpkgs tree.
135
136## Installing insecure packages {#sec-allow-insecure}
137
138There are several ways to tweak how Nix handles a package which has been marked as insecure.
139
140- To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools:
141
142 ```ShellSession
143 $ export NIXPKGS_ALLOW_INSECURE=1
144 ```
145
146- 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.
147
148 The following example configuration permits the installation of the hypothetically insecure package `hello`, version `1.2.3`:
149
150 ```nix
151 {
152 permittedInsecurePackages = [
153 "hello-1.2.3"
154 ];
155 }
156 ```
157
158- It is also possible to create a custom policy around which insecure packages to allow and deny, by overriding the `allowInsecurePredicate` configuration option.
159
160 The `allowInsecurePredicate` option is a function which accepts a package and returns a boolean, much like `allowUnfreePredicate`.
161
162 The following configuration example only allows insecure packages with very short names:
163
164 ```nix
165 {
166 allowInsecurePredicate = pkg: builtins.stringLength (lib.getName pkg) <= 5;
167 }
168 ```
169
170 Note that `permittedInsecurePackages` is only checked if `allowInsecurePredicate` is not specified.
171
172## Modify packages via `packageOverrides` {#sec-modify-via-packageOverrides}
173
174You 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.
175
176```nix
177{
178 packageOverrides = pkgs: rec {
179 foo = pkgs.foo.override { ... };
180 };
181}
182```
183
184## `config` Options Reference {#sec-config-options-reference}
185
186The following attributes can be passed in [`config`](#chap-packageconfig).
187
188```{=include=} options
189id-prefix: opt-
190list-id: configuration-variable-list
191source: ../config-options.json
192```
193
194
195## Declarative Package Management {#sec-declarative-package-management}
196
197### Build an environment {#sec-building-environment}
198
199Using `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`:
200
201```nix
202{
203 packageOverrides = pkgs: with pkgs; {
204 myPackages = pkgs.buildEnv {
205 name = "my-packages";
206 paths = [
207 aspell
208 bc
209 coreutils
210 gdb
211 ffmpeg
212 nixUnstable
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 = pkgs: with pkgs; {
228 myPackages = pkgs.buildEnv {
229 name = "my-packages";
230 paths = [
231 aspell
232 bc
233 coreutils
234 gdb
235 ffmpeg
236 nixUnstable
237 emscripten
238 jq
239 nox
240 silver-searcher
241 ];
242 pathsToLink = [ "/share" "/bin" ];
243 };
244 };
245}
246```
247
248`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.
249
250### Getting documentation {#sec-getting-documentation}
251
252After 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.
253
254```nix
255{
256 packageOverrides = pkgs: with pkgs; {
257 myPackages = pkgs.buildEnv {
258 name = "my-packages";
259 paths = [
260 aspell
261 bc
262 coreutils
263 ffmpeg
264 nixUnstable
265 emscripten
266 jq
267 nox
268 silver-searcher
269 ];
270 pathsToLink = [ "/share/man" "/share/doc" "/bin" ];
271 extraOutputsToInstall = [ "man" "doc" ];
272 };
273 };
274}
275```
276
277This 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.
278
279```nix
280{
281 packageOverrides = pkgs: with pkgs; rec {
282 myProfile = writeText "my-profile" ''
283 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
284 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
285 '';
286 myPackages = pkgs.buildEnv {
287 name = "my-packages";
288 paths = [
289 (runCommand "profile" {} ''
290 mkdir -p $out/etc/profile.d
291 cp ${myProfile} $out/etc/profile.d/my-profile.sh
292 '')
293 aspell
294 bc
295 coreutils
296 ffmpeg
297 man
298 nixUnstable
299 emscripten
300 jq
301 nox
302 silver-searcher
303 ];
304 pathsToLink = [ "/share/man" "/share/doc" "/bin" "/etc" ];
305 extraOutputsToInstall = [ "man" "doc" ];
306 };
307 };
308}
309```
310
311For 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:
312
313```ShellSession
314#!/bin/sh
315if [ -d "${HOME}/.nix-profile/etc/profile.d" ]; then
316 for i in "${HOME}/.nix-profile/etc/profile.d/"*.sh; do
317 if [ -r "$i" ]; then
318 . "$i"
319 fi
320 done
321fi
322```
323
324Now just run `. "${HOME}/.profile"` and you can start loading man pages from your environment.
325
326### GNU info setup {#sec-gnu-info-setup}
327
328Configuring 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.
329
330```nix
331{
332 packageOverrides = pkgs: with pkgs; rec {
333 myProfile = writeText "my-profile" ''
334 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
335 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
336 export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
337 '';
338 myPackages = pkgs.buildEnv {
339 name = "my-packages";
340 paths = [
341 (runCommand "profile" {} ''
342 mkdir -p $out/etc/profile.d
343 cp ${myProfile} $out/etc/profile.d/my-profile.sh
344 '')
345 aspell
346 bc
347 coreutils
348 ffmpeg
349 man
350 nixUnstable
351 emscripten
352 jq
353 nox
354 silver-searcher
355 texinfoInteractive
356 ];
357 pathsToLink = [ "/share/man" "/share/doc" "/share/info" "/bin" "/etc" ];
358 extraOutputsToInstall = [ "man" "doc" "info" ];
359 postBuild = ''
360 if [ -x $out/bin/install-info -a -w $out/share/info ]; then
361 shopt -s nullglob
362 for i in $out/share/info/*.info $out/share/info/*.info.gz; do
363 $out/bin/install-info $i $out/share/info/dir
364 done
365 fi
366 '';
367 };
368 };
369}
370```
371
372`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.