<chapter 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-garbage-collection'>

<title>Garbage Collection</title>

<para><command>nix-env</command> operations such as upgrades
(<option>-u</option>) and uninstall (<option>-e</option>) never
actually delete packages from the system.  All they do (as shown
above) is to create a new user environment that no longer contains
symlinks to the “deleted” packages.</para>

<para>Of course, since disk space is not infinite, unused packages
should be removed at some point.  You can do this by running the Nix
garbage collector.  It will remove from the Nix store any package
not used (directly or indirectly) by any generation of any
profile.</para>

<para>Note however that as long as old generations reference a
package, it will not be deleted.  After all, we wouldn’t be able to
do a rollback otherwise.  So in order for garbage collection to be
effective, you should also delete (some) old generations.  Of course,
this should only be done if you are certain that you will not need to
roll back.</para>

<para>To delete all old (non-current) generations of your current
profile:

<screen>
$ nix-env --delete-generations old</screen>

Instead of <literal>old</literal> you can also specify a list of
generations, e.g.,

<screen>
$ nix-env --delete-generations 10 11 14</screen>

To delete all generations older than a specified number of days
(except the current generation), use the <literal>d</literal>
suffix. For example,

<screen>
$ nix-env --delete-generations 14d</screen>

deletes all generations older than two weeks.</para>

<para>After removing appropriate old generations you can run the
garbage collector as follows:

<screen>
$ nix-store --gc</screen>

The behaviour of the gargage collector is affected by the 
<literal>keep-derivations</literal> (default: true) and <literal>keep-outputs</literal>
(default: false) options in the Nix configuration file. The defaults will ensure
that all derivations that are build-time dependencies of garbage collector roots
will be kept and that all output paths that are runtime dependencies
will be kept as well. All other derivations or paths will be collected. 
(This is usually what you want, but while you are developing
it may make sense to keep outputs to ensure that rebuild times are quick.)

If you are feeling uncertain, you can also first view what files would
be deleted:

<screen>
$ nix-store --gc --print-dead</screen>

Likewise, the option <option>--print-live</option> will show the paths
that <emphasis>won’t</emphasis> be deleted.</para>

<para>There is also a convenient little utility
<command>nix-collect-garbage</command>, which when invoked with the
<option>-d</option> (<option>--delete-old</option>) switch deletes all
old generations of all profiles in
<filename>/nix/var/nix/profiles</filename>.  So

<screen>
$ nix-collect-garbage -d</screen>

is a quick and easy way to clean up your system.</para>

<xi:include href="garbage-collector-roots.xml" />

</chapter>