nix-env manipulate or query Nix user environments nix-env &opt-common-syn; --file -f path --profile -p path --dry-run operation options arguments The command nix-env is used to manipulate Nix user environments. User environments are sets of software components available to a user at some point in time. In other words, they are a synthesised view of the programs available in the Nix store. There may be many user environments: different users can have different environments, and individual users can switch between different environments. nix-env 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. &opt-common; --file / -f Specifies the Nix expression (designated below as the active Nix expression) used by the --install, --upgrade, and --query --available operations to obtain derivations. The default is ~/.nix-defexpr. --profile / -p Specifies the profile to be used by those operations that operate on a profile (designated below as the active profile). A profile is sequence of user environments called generations, one of which is the current generation. The default profile is the target of the symbolic link ~/.nix-profile (see below). --dry-run For the --install, --upgrade, --uninstall, --switch-generation and --rollback operations, this flag will cause nix-env to print what would be done if this flag had not been specified, without actually doing it. ~/.nix-defexpr The default Nix expression used by the --install, --upgrade, and --query --available operations to obtain derivations. It is generally a symbolic link to some other location set using the --import operation. The --file option may be used to override this default. ~/.nix-profile A symbolic link to the user's current profile. By default, this symlink points to prefix/var/nix/profiles/default. The PATH environment variable should include ~/.nix-profile/bin for the user environment to be visible to the user. nix-env --install -i drvnames The install operation creates a new user environment, based on the current generation of the active profile, to which the derivations designated by drvnames in the active Nix expression are added. $ nix-env --install gcc-3.3.2 (install specific version) $ nix-env --install gcc (just pick any version) $ nix-env -f ~/foo.nix -i '*' (install everything in foo.nix) nix-env --upgrade -u --lt --leq --always drvnames The upgrade operation creates a new user environment, based on the current generation of the active profile, in which all derivations designated by drvnames for which there are newer versions in the active Nix expression are replaced by those newer versions. Matching derivations for which there are no newer versions are left untouched; this is not an error. It is also not an error if an element of drvnames matches no installed derivations. If multiple derivations in the active Nix expression match an installed derivation, the one with the highest version is selected. --lt Only upgrade a derivation to newer versions. This is the default. --leq In addition to upgrading to newer versions, also upgrade to derivations that have the same version. Version are not a unique identification of a derivation, so there may be many derivations that have the same version. This flag may be useful to force synchronisation between the installed and available derivations. --always In addition to upgrading to newer versions, also upgrade to derivations that have the same or a lower version. I.e., derivations may actually be downgraded depending on what is available in the active Nix expression. $ nix-env --upgrade gcc upgrading `gcc-3.3.1' to `gcc-3.4' $ nix-env -u gcc-3.3.2 --always (switch to a specific version) upgrading `gcc-3.4' to `gcc-3.3.2' $ nix-env --upgrade pan (no upgrades available, so nothing happens) $ nix-env -u '*' (try to upgrade everything) upgrading `hello-2.1.2' to `hello-2.1.3' upgrading `mozilla-1.2' to `mozilla-1.4' The upgrade operation determines whether a derivation y is an upgrade of a derivation x by looking at their respective name attributes. The names (e.g., gcc-3.3.1 are split into two parts: the package name (gcc), and the version (3.3.1). The version part starts after the first dash not following by a letter. x is considered an upgrade of y if their package names match, and the version of y is higher that that of x. The versions are compared by splitting them into contiguous components of numbers and letters. E.g., 3.3.1pre5 is split into [3, 3, 1, "pre", 5]. These lists are then compared lexicographically (from left to right). Corresponding components a and b are compared as follows. If they are both numbers, integer comparison is used. If a is an empty string and b is a number, a is considered less than b. The special string component pre (for pre-release) is considered to be less than other components. String components are considered less than number components. Otherwise, they are compared lexicographically (i.e., using case-sensitive string comparison). This is illustrated by the following examples: 1.0 < 2.3 2.1 < 2.3 2.3 = 2.3 2.5 > 2.3 3.1 > 2.3 2.3.1 > 2.3 2.3.1 > 2.3a 2.3pre1 < 2.3 2.3pre3 < 2.3pre12 2.3a < 2.3c 2.3pre1 < 2.3c 2.3pre1 < 2.3q nix-env --uninstall -e drvnames The uninstall operation creates a new user environment, based on the current generation of the active profile, from which the derivations designated by drvnames are removed. $ nix-env --uninstall gcc $ nix-env -e '*' (remove everything) nix-env --query -q --installed --available -a --name --expr --status -s The query operation displays information about either the derivations that are installed in the current generation of the active profile (--installed), or the derivations that are available for installation in the active Nix expression (--available). The derivations are sorted by their name attributes. The following flags specify the set of derivations on which the query operates. --installed The query operates on the derivations that are installed in the current generation of the active profile. This is the default --available / -a The query operates on the derivations that are available in the active Nix expression. The following flags specify what information to display about the selected derivations. Only one type of query may be specified. --name Prints the name attribute of each derivation. This is the default. --expr Prints the store expression in the Nix store that described the derivation. --status / -s Prints the status of each derivation, followed by its name attribute. The status consists of three characters. The first is I or -, indicating whether the derivation is currently installed in the current generation of the active profile. This is by definition the case for --installed, but not for --available. The second is P or -, indicating whether the derivation is present on the system. This indicates whether installation of an available derivation will require the derivation to be built. The third is S or -, indicating whether a substitute is available for the derivation. $ nix-env -q (show installed derivations) MozillaFirebird-0.7 bison-1.875c docbook-xml-4.2 ... $ nix-env -qa (show available derivations) GConf-2.4.0.1 MPlayer-1.0pre3 MozillaFirebird-0.7 ORBit2-2.8.3 ... $ nix-env -qas (show status of available derivations) -P- GConf-2.4.0.1 (not installed but present) --S MPlayer-1.0pre3 (not present, but there is a substitute for fast installation) --S MozillaFirebird-0.7 (i.e., this is not the installed Firebird, even though the version is the same!) IP- bison-1.875c (installed and by definition present) ... $ nix-env -f ./foo.nix -qa (show available derivations in the Nix expression foo.nix) foo-1.2.3 nix-env --switch-profile -S path This operation makes path the current profile for the user. That is, the symlink ~/.nix-profile is made to point to path. $ nix-env -S ~/my-profile nix-env --list-generations This operation print a list of all the currently existing generations for the active profile. These may be switched to using the --switch-generation operation. It also prints the creation date of the generation, and indicates the current generation. $ nix-env --list-generations 95 2004-02-06 11:48:24 96 2004-02-06 11:49:01 97 2004-02-06 16:22:45 98 2004-02-06 16:24:33 (current) nix-env --switch-generation -G generation This operation makes generation number generation the current generation of the active profile. That is, if the profile is the path to the active profile, then the symlink profile is made to point to profile-generation-link, which is in turn a symlink to the actual user environment in the Nix store. Switching will fail if the specified generation does not exist. $ nix-env -G 42 switching from generation 50 to 42 nix-env --rollback This operation switches to the previous generation of the active profile, that is, the highest numbered generation lower than the current generation, if it exists. It is just a convenience wrapper around --list-generations and --switch-generation. $ nix-env --rollback switching from generation 92 to 91 $ nix-env --rolback error: no generation older than the current (91) exists nix-env --import -I path This operation makes path the default active Nix expression for the user. That is, the symlink ~/.nix-userenv is made to point to path. $ nix-env -I ~/nixpkgs-0.5/