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
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## Declarative Package Management {#sec-declarative-package-management}
180
181### Build an environment {#sec-building-environment}
182
183Using `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`:
184
185```nix
186{
187 packageOverrides = pkgs: with pkgs; {
188 myPackages = pkgs.buildEnv {
189 name = "my-packages";
190 paths = [
191 aspell
192 bc
193 coreutils
194 gdb
195 ffmpeg
196 nixUnstable
197 emscripten
198 jq
199 nox
200 silver-searcher
201 ];
202 };
203 };
204}
205```
206
207To 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:
208
209```nix
210{
211 packageOverrides = pkgs: with pkgs; {
212 myPackages = pkgs.buildEnv {
213 name = "my-packages";
214 paths = [
215 aspell
216 bc
217 coreutils
218 gdb
219 ffmpeg
220 nixUnstable
221 emscripten
222 jq
223 nox
224 silver-searcher
225 ];
226 pathsToLink = [ "/share" "/bin" ];
227 };
228 };
229}
230```
231
232`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.
233
234### Getting documentation {#sec-getting-documentation}
235
236After 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.
237
238```nix
239{
240 packageOverrides = pkgs: with pkgs; {
241 myPackages = pkgs.buildEnv {
242 name = "my-packages";
243 paths = [
244 aspell
245 bc
246 coreutils
247 ffmpeg
248 nixUnstable
249 emscripten
250 jq
251 nox
252 silver-searcher
253 ];
254 pathsToLink = [ "/share/man" "/share/doc" "/bin" ];
255 extraOutputsToInstall = [ "man" "doc" ];
256 };
257 };
258}
259```
260
261This 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.
262
263```nix
264{
265 packageOverrides = pkgs: with pkgs; rec {
266 myProfile = writeText "my-profile" ''
267 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
268 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
269 '';
270 myPackages = pkgs.buildEnv {
271 name = "my-packages";
272 paths = [
273 (runCommand "profile" {} ''
274 mkdir -p $out/etc/profile.d
275 cp ${myProfile} $out/etc/profile.d/my-profile.sh
276 '')
277 aspell
278 bc
279 coreutils
280 ffmpeg
281 man
282 nixUnstable
283 emscripten
284 jq
285 nox
286 silver-searcher
287 ];
288 pathsToLink = [ "/share/man" "/share/doc" "/bin" "/etc" ];
289 extraOutputsToInstall = [ "man" "doc" ];
290 };
291 };
292}
293```
294
295For 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:
296
297```ShellSession
298#!/bin/sh
299if [ -d $HOME/.nix-profile/etc/profile.d ]; then
300 for i in $HOME/.nix-profile/etc/profile.d/*.sh; do
301 if [ -r $i ]; then
302 . $i
303 fi
304 done
305fi
306```
307
308Now just run `source $HOME/.profile` and you can starting loading man pages from your environment.
309
310### GNU info setup {#sec-gnu-info-setup}
311
312Configuring 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.
313
314```nix
315{
316 packageOverrides = pkgs: with pkgs; rec {
317 myProfile = writeText "my-profile" ''
318 export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin
319 export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man
320 export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info
321 '';
322 myPackages = pkgs.buildEnv {
323 name = "my-packages";
324 paths = [
325 (runCommand "profile" {} ''
326 mkdir -p $out/etc/profile.d
327 cp ${myProfile} $out/etc/profile.d/my-profile.sh
328 '')
329 aspell
330 bc
331 coreutils
332 ffmpeg
333 man
334 nixUnstable
335 emscripten
336 jq
337 nox
338 silver-searcher
339 texinfoInteractive
340 ];
341 pathsToLink = [ "/share/man" "/share/doc" "/share/info" "/bin" "/etc" ];
342 extraOutputsToInstall = [ "man" "doc" "info" ];
343 postBuild = ''
344 if [ -x $out/bin/install-info -a -w $out/share/info ]; then
345 shopt -s nullglob
346 for i in $out/share/info/*.info $out/share/info/*.info.gz; do
347 $out/bin/install-info $i $out/share/info/dir
348 done
349 fi
350 '';
351 };
352 };
353}
354```
355
356`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.