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