pyrox.dev
1# Adding Custom Packages {#sec-custom-packages}
2
3It's possible that a package you need is not available in NixOS. In that
4case, you can do two things. Either you can package it with Nix, or you can try
5to use prebuilt packages from upstream. Due to the peculiarities of NixOS, it
6is important to note that building software from source is often easier than
7using pre-built executables.
8
9## Building with Nix {#sec-custom-packages-nix}
10
11This can be done either in-tree or out-of-tree. For an in-tree build, you can
12clone the Nixpkgs repository, add the package to your clone, and (optionally)
13submit a patch or pull request to have it accepted into the main Nixpkgs
14repository. This is described in detail in the [Nixpkgs
15manual](https://nixos.org/nixpkgs/manual). In short, you clone Nixpkgs:
16
17```ShellSession
18$ git clone https://github.com/NixOS/nixpkgs
19$ cd nixpkgs
20```
21
22Then you write and test the package as described in the Nixpkgs manual.
23Finally, you add it to [](#opt-environment.systemPackages), e.g.
24
25```nix
26{
27 environment.systemPackages = [ pkgs.my-package ];
28}
29```
30
31and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
32
33```ShellSession
34# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
35```
36
37The second possibility is to add the package outside of the Nixpkgs
38tree. For instance, here is how you specify a build of the
39[GNU Hello](https://www.gnu.org/software/hello/) package directly in
40`configuration.nix`:
41
42```nix
43{
44 environment.systemPackages =
45 let
46 my-hello = with pkgs; stdenv.mkDerivation rec {
47 name = "hello-2.8";
48 src = fetchurl {
49 url = "mirror://gnu/hello/${name}.tar.gz";
50 hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
51 };
52 };
53 in
54 [ my-hello ];
55}
56```
57
58Of course, you can also move the definition of `my-hello` into a
59separate Nix expression, e.g.
60
61```nix
62{
63 environment.systemPackages = [ (import ./my-hello.nix) ];
64}
65```
66
67where `my-hello.nix` contains:
68
69```nix
70with import <nixpkgs> {}; # bring all of Nixpkgs into scope
71
72stdenv.mkDerivation rec {
73 name = "hello-2.8";
74 src = fetchurl {
75 url = "mirror://gnu/hello/${name}.tar.gz";
76 hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
77 };
78}
79```
80
81This allows testing the package easily:
82
83```ShellSession
84$ nix-build my-hello.nix
85$ ./result/bin/hello
86Hello, world!
87```
88
89## Using pre-built executables {#sec-custom-packages-prebuilt}
90
91Most pre-built executables will not work on NixOS. There are two notable
92exceptions: flatpaks and AppImages. For flatpaks see the [dedicated
93section](#module-services-flatpak). AppImages can run "as-is" on NixOS.
94
95First you need to enable AppImage support: add to `/etc/nixos/configuration.nix`
96
97```nix
98{
99 programs.appimage.enable = true;
100 programs.appimage.binfmt = true;
101}
102```
103
104Then you can run the AppImage "as-is" or with `appimage-run foo.appimage`.
105
106If there are shared libraries missing add them with
107
108```nix
109{
110 programs.appimage.package = pkgs.appimage-run.override {
111 extraPkgs = pkgs: [
112 # missing libraries here, e.g.: `pkgs.libepoxy`
113 ];
114 }
115}
116```
117
118To make other pre-built executables work on NixOS, you need to package them
119with Nix and special helpers like `autoPatchelfHook` or `buildFHSEnv`. See
120the [Nixpkgs manual](https://nixos.org/nixpkgs/manual) for details. This
121is complex and often doing a source build is easier.