diff --git a/nixos/doc/manual/configuration/adding-custom-packages.section.md b/nixos/doc/manual/configuration/adding-custom-packages.section.md
index 5d1198fb0f41..9219396722f0 100644
--- a/nixos/doc/manual/configuration/adding-custom-packages.section.md
+++ b/nixos/doc/manual/configuration/adding-custom-packages.section.md
@@ -1,11 +1,18 @@
# Adding Custom Packages {#sec-custom-packages}
It's possible that a package you need is not available in NixOS. In that
-case, you can do two things. First, you can clone the Nixpkgs
-repository, add the package to your clone, and (optionally) submit a
-patch or pull request to have it accepted into the main Nixpkgs repository.
-This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
-In short, you clone Nixpkgs:
+case, you can do two things. Either you can package it with Nix, or you can try
+to use prebuilt packages from upstream. Due to the peculiarities of NixOS, it
+is important to note that building software from source is often easier than
+using pre-built executables.
+
+## Building with Nix {#sec-custom-packages-nix}
+
+This can be done either in-tree or out-of-tree. For an in-tree build, you can
+clone the Nixpkgs repository, add the package to your clone, and (optionally)
+submit a patch or pull request to have it accepted into the main Nixpkgs
+repository. This is described in detail in the [Nixpkgs
+manual](https://nixos.org/nixpkgs/manual). In short, you clone Nixpkgs:
```ShellSession
$ git clone https://github.com/NixOS/nixpkgs
@@ -72,3 +79,21 @@ $ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!
```
+
+## Using pre-built executables {#sec-custom-packages-prebuilt}
+
+Most pre-built executables will not work on NixOS. There are two notable
+exceptions: flatpaks and AppImages. For flatpaks see the [dedicated
+section](#module-services-flatpak). AppImages will not run "as-is" on NixOS.
+First you need to install `appimage-run`: add to `/etc/nixos/configuration.nix`
+
+```nix
+environment.systemPackages = [ pkgs.appimage-run ];
+```
+
+Then instead of running the AppImage "as-is", run `appimage-run foo.appimage`.
+
+To make other pre-built executables work on NixOS, you need to package them
+with Nix and special helpers like `autoPatchelfHook` or `buildFHSUserEnv`. See
+the [Nixpkgs manual](https://nixos.org/nixpkgs/manual) for details. This
+is complex and often doing a source build is easier.
diff --git a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml
index 4fa40d61966e..07f541666cbe 100644
--- a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml
+++ b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml
@@ -2,40 +2,50 @@
Adding Custom Packages
It’s possible that a package you need is not available in NixOS. In
- that case, you can do two things. First, you can clone the Nixpkgs
- repository, add the package to your clone, and (optionally) submit a
- patch or pull request to have it accepted into the main Nixpkgs
- repository. This is described in detail in the
- Nixpkgs
- manual. In short, you clone Nixpkgs:
+ that case, you can do two things. Either you can package it with
+ Nix, or you can try to use prebuilt packages from upstream. Due to
+ the peculiarities of NixOS, it is important to note that building
+ software from source is often easier than using pre-built
+ executables.
-
+
+ Building with Nix
+
+ This can be done either in-tree or out-of-tree. For an in-tree
+ build, you can clone the Nixpkgs repository, add the package to
+ your clone, and (optionally) submit a patch or pull request to
+ have it accepted into the main Nixpkgs repository. This is
+ described in detail in the
+ Nixpkgs
+ manual. In short, you clone Nixpkgs:
+
+
$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs
-
- Then you write and test the package as described in the Nixpkgs
- manual. Finally, you add it to
- , e.g.
-
-
+
+ Then you write and test the package as described in the Nixpkgs
+ manual. Finally, you add it to
+ , e.g.
+
+
environment.systemPackages = [ pkgs.my-package ];
-
- and you run nixos-rebuild, specifying your own
- Nixpkgs tree:
-
-
+
+ and you run nixos-rebuild, specifying your own
+ Nixpkgs tree:
+
+
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
-
- The second possibility is to add the package outside of the Nixpkgs
- tree. For instance, here is how you specify a build of the
- GNU
- Hello package directly in
- configuration.nix:
-
-
+
+ The second possibility is to add the package outside of the
+ Nixpkgs tree. For instance, here is how you specify a build of the
+ GNU
+ Hello package directly in
+ configuration.nix:
+
+
environment.systemPackages =
let
my-hello = with pkgs; stdenv.mkDerivation rec {
@@ -48,17 +58,17 @@ environment.systemPackages =
in
[ my-hello ];
-
- Of course, you can also move the definition of
- my-hello into a separate Nix expression, e.g.
-
-
+
+ Of course, you can also move the definition of
+ my-hello into a separate Nix expression, e.g.
+
+
environment.systemPackages = [ (import ./my-hello.nix) ];
-
- where my-hello.nix contains:
-
-
+
+ where my-hello.nix contains:
+
+
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
stdenv.mkDerivation rec {
@@ -69,12 +79,40 @@ stdenv.mkDerivation rec {
};
}
-
- This allows testing the package easily:
-
-
+
+ This allows testing the package easily:
+
+
$ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!
+
+
+ Using pre-built executables
+
+ Most pre-built executables will not work on NixOS. There are two
+ notable exceptions: flatpaks and AppImages. For flatpaks see the
+ dedicated section.
+ AppImages will not run as-is on NixOS. First you
+ need to install appimage-run: add to
+ /etc/nixos/configuration.nix
+
+
+environment.systemPackages = [ pkgs.appimage-run ];
+
+
+ Then instead of running the AppImage as-is, run
+ appimage-run foo.appimage.
+
+
+ To make other pre-built executables work on NixOS, you need to
+ package them with Nix and special helpers like
+ autoPatchelfHook or
+ buildFHSUserEnv. See the
+ Nixpkgs
+ manual for details. This is complex and often doing a
+ source build is easier.
+
+