1 files changed, 61 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml
new file mode 100644
index 000000000000..c7e882d846fa
--- /dev/null
+++ b/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml
@@ -0,0 +1,61 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="sec-ad-hoc-packages">
+ <title>Ad-Hoc Package Management</title>
+
+ <para>
+  With the command <command>nix-env</command>, you can install and uninstall
+  packages from the command line. For instance, to install Mozilla Thunderbird:
+<screen>
+<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>
+  If you invoke this as root, the package is installed in the Nix profile
+  <filename>/nix/var/nix/profiles/default</filename> and visible to all users
+  of the system; otherwise, the package ends up in
+  <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
+  and is not visible to other users. The <option>-A</option> flag specifies the
+  package by its attribute name; without it, the package is installed by
+  matching against its package name (e.g. <literal>thunderbird</literal>). The
+  latter is slower because it requires matching against all available Nix
+  packages, and is ambiguous if there are multiple matching packages.
+ </para>
+
+ <para>
+  Packages come from the NixOS channel. You typically upgrade a package by
+  updating to the latest version of the NixOS channel:
+<screen>
+<prompt>$ </prompt>nix-channel --update nixos
+</screen>
+  and then running <literal>nix-env -i</literal> again. Other packages in the
+  profile are <emphasis>not</emphasis> affected; this is the crucial difference
+  with the declarative style of package management, where running
+  <command>nixos-rebuild switch</command> causes all packages to be updated to
+  their current versions in the NixOS channel. You can however upgrade all
+  packages for which there is a newer version by doing:
+<screen>
+<prompt>$ </prompt>nix-env -u '*'
+</screen>
+ </para>
+
+ <para>
+  A package can be uninstalled using the <option>-e</option> flag:
+<screen>
+<prompt>$ </prompt>nix-env -e thunderbird
+</screen>
+ </para>
+
+ <para>
+  Finally, you can roll back an undesirable <command>nix-env</command> action:
+<screen>
+<prompt>$ </prompt>nix-env --rollback
+</screen>
+ </para>
+
+ <para>
+  <command>nix-env</command> has many more flags. For details, see the
+  <citerefentry>
+  <refentrytitle>nix-env</refentrytitle>
+  <manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual.
+ </para>
+</section>