nixos/doc/manual/configuration/adding-custom-packages.section.md

   1 # Adding Custom Packages {#sec-custom-packages}
   2
   3 It's possible that a package you need is not available in NixOS. In that
   4 case, you can do two things. Either you can package it with Nix, or you can try
   5 to use prebuilt packages from upstream. Due to the peculiarities of NixOS, it
   6 is important to note that building software from source is often easier than
   7 using pre-built executables.
   8
   9 ## Building with Nix {#sec-custom-packages-nix}
  10
  11 This can be done either in-tree or out-of-tree. For an in-tree build, you can
  12 clone the Nixpkgs repository, add the package to your clone, and (optionally)
  13 submit a patch or pull request to have it accepted into the main Nixpkgs
  14 repository. This is described in detail in the [Nixpkgs
  15 manual](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
  22 Then you write and test the package as described in the Nixpkgs manual.
  23 Finally, you add it to [](#opt-environment.systemPackages), e.g.
  24
  25 ```nix
  26 {
  27   environment.systemPackages = [ pkgs.my-package ];
  28 }
  29 ```
  30
  31 and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
  32
  33 ```ShellSession
  34 # nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
  35 ```
  36
  37 The second possibility is to add the package outside of the Nixpkgs
  38 tree. 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
  58 Of course, you can also move the definition of `my-hello` into a
  59 separate Nix expression, e.g.
  60
  61 ```nix
  62 {
  63   environment.systemPackages = [ (import ./my-hello.nix) ];
  64 }
  65 ```
  66
  67 where `my-hello.nix` contains:
  68
  69 ```nix
  70 with import <nixpkgs> {}; # bring all of Nixpkgs into scope
  71
  72 stdenv.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
  81 This allows testing the package easily:
  82
  83 ```ShellSession
  84 $ nix-build my-hello.nix
  85 $ ./result/bin/hello
  86 Hello, world!
  87 ```
  88
  89 ## Using pre-built executables {#sec-custom-packages-prebuilt}
  90
  91 Most pre-built executables will not work on NixOS. There are two notable
  92 exceptions: flatpaks and AppImages. For flatpaks see the [dedicated
  93 section](#module-services-flatpak). AppImages will not run "as-is" on NixOS.
  94 First you need to install `appimage-run`: add to `/etc/nixos/configuration.nix`
  95
  96 ```nix
  97 {
  98   environment.systemPackages = [ pkgs.appimage-run ];
  99 }
 100 ```
 101
 102 Then instead of running the AppImage "as-is", run `appimage-run foo.appimage`.
 103
 104 To make other pre-built executables work on NixOS, you need to package them
 105 with Nix and special helpers like `autoPatchelfHook` or `buildFHSEnv`. See
 106 the [Nixpkgs manual](https://nixos.org/nixpkgs/manual) for details. This
 107 is complex and often doing a source build is easier.