nix-store manipulate or query the Nix store nix-store --add-root path --indirect operation options arguments The command nix-store performs primitive operations on the Nix store. You generally do not need to run this command manually. nix-store takes exactly one operation flag which indicates the subcommand to be performed. These are documented below. This section lists the options that are common to all operations. These options are allowed for every subcommand, though they may not always have an effect. See also for a list of common options. --add-root path Causes the result of a build action (--realise and --force-realise) to be registered as a root of the garbage collector (see ). The root is stored in path, which must be inside a directory that is scanned for roots by the garbage collector (i.e., typically in a subdirectory of /nix/var/nix/gcroots/) unless the --indirect flag is used. --indirect In conjunction with --add-root, this option allows roots to be stored outside of the GC roots directory. This is useful for commands such as nix-build that place a symlink to the build result in the current directory; such a build result should not be garbage-collected unless the symlink is removed. The --indirect flag causes a uniquely named symlink to path to be stored in /nix/var/nix/gcroots/auto/. For instance, $ nix-store --add-root /home/eelco/bla/result --indirect -r ... $ ls -l /nix/var/nix/gcroots/auto lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result $ ls -l /home/eelco/bla/result lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10 Thus, when /home/eelco/bla/result is removed, the GC root in the auto directory becomes a dangling symlink and will be ignored by the collector. Note that it is not possible to move or rename indirect GC roots, since the symlink in the auto directory will still point to the old location. nix-store --realise -r paths The operation --install realises in the file system the store expressions stored in paths. If these expressions are derivation expressions, they are first normalised into a closure expression. This may happen in two ways. First, the corresponding closure expression (the successor) may already known (either because the build has already been performed, or because a successor was explicitly registered through the --successor operation). Otherwise, the build action described by the derivation is performed, and a closure expression is computed by scanning the result of the build for references to other paths in the store. The paths of the closure expression corresponding to each expression in paths is printed on standard output. nix-store --gc --print-roots --print-live --print-dead --delete Without additional flags, the operation --gc performs a garbage collection on the Nix store. That is, all paths in the Nix store not reachable via file system references from a set of roots, are deleted. The following suboperations may be specified: --print-roots This operation prints on standard output the set of roots used by the garbage collector. --print-live This operation prints on standard output the set of live store paths, which are all the store paths reachable from the roots. Live paths should never be deleted, since that would break consistency — it would become possible that applications are installed that reference things that are no longer present in the store. --print-dead This operation prints out on standard output the set of dead store paths, which is just the opposite of the set of live paths: any path in the store that is not live (with respect to the roots) is dead. --delete This operation performs an actual garbage collection. All dead paths are removed from the store. This is the default. The roots of the garbage collector are all store paths to which there are symlinks in the directory prefix/nix/var/nix/gcroots. For instance, the following command makes the path /nix/store/d718ef...-foo a root of the collector: $ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar That is, after this command, the garbage collector will not remove /nix/store/d718ef...-foo or any of its dependencies. Subdirectories of prefix/nix/var/nix/gcroots are also searched for symlinks. Symlinks to non-store paths are followed and searched for roots, but TODO. TODO To delete all unreachable paths, just do: $ nix-store --gc nix-store --query -q --list -l --requisites -R --predecessors --graph --normalise -n --force-realise -f args The operation --query displays various bits of information about store paths. The queries are described below. At most one query can be specified. The default query is --list. --use-output / -u For each argument to the query that is a store derivation, apply the query to the output path of the derivation instead. --force-realise / -f Realise each argument to the query first (see nix-store --realise). --list / -l Prints out the output paths of the store expressions indicated by the identifiers args. In the case of a derivation expression, these are the paths that will be produced when the derivation is realised. In the case of a closure expression, these are the paths that were produced the derivation expression of which the closure expression is a successor. --requisites / -R Prints out the requisite paths of the store expressions indicated by the identifiers args. The requisite paths of a Nix expression are the paths that need to be present in the system to be able to realise the expression. That is, they form the closure of the expression in the file system (i.e., no path in the set of requisite paths points to anything outside the set of requisite paths). The notion of requisite paths is very useful when one wants to distribute store expressions. Since they form a closure, they are the only paths one needs to distribute to another system to be able to realise the expression on the other system. This query is generally used to implement various kinds of deployment. A source deployment is obtained by distributing the requisite paths of a derivation expression. A binary deployment is obtained by distributing the requisite paths of a closure expression. A cache deployment is obtained by distributing the requisite paths of a derivation expression and specifying the option --include-successors. This will include not just the paths of a source and binary deployment, but also all expressions and paths of subterms of the source. This is useful if one wants to realise on the target system a Nix expression that is similar but not quite the same as the one being distributed, since any common subterms will be reused. This query has one option: --include-outputs Also include the output path of store derivations, and their closures. --graph Prints a graph of the closure of the store expressions identified by args in the format of the dot tool of AT&T's GraphViz package. nix-store --register-validity TODO nix-store --substitute srcpath subpath The operation --substitute registers that the store path srcpath can be built by realising the derivation expression in subpath. This is used to implement binary deployment. nix-store --verify The operation --verify verifies the internal consistency of the Nix database, and the consistency between the Nix database and the Nix store. Any inconsistencies encountered are automatically repaired. Inconsistencies are generally the result of the Nix store or database being modified by non-Nix tools, or of bugs in Nix itself.