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 realisation (--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. If there are multiple results, then multiple symlinks will be created by sequentially numbering symlinks beyond the first one (e.g., foo, foo-2, foo-3, and so on). --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 --realise essentially “builds” the specified store paths. Realisation is a somewhat overloaded term: If the store path is a derivation, realisation ensures that the output paths of the derivation are valid (i.e., the output path and its closure exist in the file system). This can be done in several ways. First, it is possible that the outputs are already valid, in which case we are done immediately. Otherwise, there may be substitutes that produce the outputs (e.g., by downloading them). Finally, the outputs can be produced by performing the build action described by the derivation. If the store path is not a derivation, realisation ensures that the specified path is valid (i.e., it and its closure exist in the file system). If the path is already valid, we are done immediately. Otherwise, the path and any missing paths in its closure may be produced through substitutes. If there are no (succesful) subsitutes, realisation fails. The output path of each derivation is printed on standard output. (For non-derivations argument, the argument itself is printed.) This operation is typically used to build store derivations produced by nix-instantiate: $ nix-store -r $(nix-instantiate ./foo.nix) This is essentially what nix-build does. 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.