pyrox.dev
1# Customising Packages {#sec-customising-packages}
2
3The Nixpkgs configuration for a NixOS system is set by the {option}`nixpkgs.config` option.
4
5::::{.example}
6# Globally allow unfree packages
7
8```nix
9{
10 nixpkgs.config = {
11 allowUnfree = true;
12 };
13}
14```
15
16:::{.note}
17This only allows unfree software in the given NixOS configuration.
18For users invoking Nix commands such as [`nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build), Nixpkgs is configured independently.
19See the [Nixpkgs manual section on global configuration](https://nixos.org/manual/nixpkgs/unstable/#chap-packageconfig) for details.
20:::
21::::
22
23<!-- TODO(@fricklerhandwerk)
24all of the following should go to the Nixpkgs manual, it has nothing to do with NixOS
25-->
26
27Some packages in Nixpkgs have options to enable or disable optional functionality, or change other aspects of the package.
28
29::: {.warning}
30Unfortunately, Nixpkgs currently lacks a way to query available package configuration options.
31:::
32
33::: {.note}
34For example, many packages come with extensions one might add.
35Examples include:
36- [`passExtensions.pass-otp`](https://search.nixos.org/packages/query=passExtensions.pass-otp)
37- [`python310Packages.requests`](https://search.nixos.org/packages/query=python310Packages.requests)
38
39You can use them like this:
40```nix
41{
42 environment.systemPackages = with pkgs; [
43 sl
44 (pass.withExtensions (subpkgs: with subpkgs; [
45 pass-audit
46 pass-otp
47 pass-genphrase
48 ]))
49 (python3.withPackages (subpkgs: with subpkgs; [
50 requests
51 ]))
52 cowsay
53 ];
54}
55```
56:::
57
58Apart from high-level options, it's possible to tweak a package in
59almost arbitrary ways, such as changing or disabling dependencies of a
60package. For instance, the Emacs package in Nixpkgs by default has a
61dependency on GTK 2. If you want to build it against GTK 3, you can
62specify that as follows:
63
64```nix
65{
66 environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
67}
68```
69
70The function `override` performs the call to the Nix function that
71produces Emacs, with the original arguments amended by the set of
72arguments specified by you. So here the function argument `gtk` gets the
73value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses
74are necessary because in Nix, function application binds more weakly
75than list construction, so without them,
76[](#opt-environment.systemPackages)
77would be a list with two elements.)
78
79Even greater customisation is possible using the function
80`overrideAttrs`. While the `override` mechanism above overrides the
81arguments of a package function, `overrideAttrs` allows changing the
82*attributes* passed to `mkDerivation`. This permits changing any aspect
83of the package, such as the source code. For instance, if you want to
84override the source code of Emacs, you can say:
85
86```nix
87{
88 environment.systemPackages = [
89 (pkgs.emacs.overrideAttrs (oldAttrs: {
90 name = "emacs-25.0-pre";
91 src = /path/to/my/emacs/tree;
92 }))
93 ];
94}
95```
96
97Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
98and produces a new derivation in which the original's `name` and `src`
99attribute have been replaced by the given values by re-calling
100`stdenv.mkDerivation`. The original attributes are accessible via the
101function argument, which is conventionally named `oldAttrs`.
102
103The overrides shown above are not global. They do not affect the
104original package; other packages in Nixpkgs continue to depend on the
105original rather than the customised package. This means that if another
106package in your system depends on the original package, you end up with
107two instances of the package. If you want to have everything depend on
108your customised instance, you can apply a *global* override as follows:
109
110```nix
111{
112 nixpkgs.config.packageOverrides = pkgs:
113 { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
114 };
115}
116```
117
118The effect of this definition is essentially equivalent to modifying the
119`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
120that depends on `emacs` will be passed your customised instance.
121(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
122refers to the original rather than overridden instance, to prevent an
123infinite recursion.)