1 files changed, 63 insertions, 0 deletions
diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixos/doc/manual/configuration/ad-hoc-packages.xml
new file mode 100644
index 000000000000..e237e20c4fff
--- /dev/null
+++ b/nixos/doc/manual/configuration/ad-hoc-packages.xml
@@ -0,0 +1,63 @@
+<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>
+$ nix-env -iA nixos.pkgs.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>
+$ 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>
+$ nix-env -u '*'
+</screen>
+</para>
+
+<para>A package can be uninstalled using the <option>-e</option>
+flag:
+<screen>
+$ nix-env -e thunderbird
+</screen>
+</para>
+
+<para>Finally, you can roll back an undesirable
+<command>nix-env</command> action:
+<screen>
+$ 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>