Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NIX-ENV(1)		       Command Reference		    NIX-ENV(1)

NAME
       nix-env - manipulate or query Nix user environments

SYNOPSIS
       nix-env [--help]	[--version] [{--verbose	| -v}...] [--quiet]
	       [--no-build-output | -Q]	[{--max-jobs | -j} number]
	       [--cores	number]	[--max-silent-time number] [--timeout number]
	       [--keep-going | -k] [--keep-failed | -K]	[--fallback]
	       [--readonly-mode] [-I path] [--option name value]
	       [--arg name value] [--argstr name value]	[{--file | -f} path]
	       [{--profile | -p} path] [--system-filter	system]	[--dry-run]
	       operation [options...] [arguments...]

DESCRIPTION
       The command nix-env is used to manipulate Nix user environments.	User
       environments are	sets of	software packages 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.

SELECTORS
       Several commands, such as nix-env -q and	nix-env	-i, take a list	of
       arguments that specify the packages on which to operate.	These are
       extended	regular	expressions that must match the	entire name of the
       package.	(For details on	regular	expressions, see regex(7).) The	match
       is case-sensitive. The regular expression can optionally	be followed by
       a dash and a version number; if omitted,	any version of the package
       will match. Here	are some examples:

       firefox
	   Matches the package name firefox and	any version.

       firefox-32.0
	   Matches the package name firefox and	version	32.0.

       gtk\\+
	   Matches the package name gtk+. The +	character must be escaped
	   using a backslash to	prevent	it from	being interpreted as a
	   quantifier, and the backslash must be escaped in turn with another
	   backslash to	ensure that the	shell passes it	on.

       .\*
	   Matches any package name. This is the default for most commands.

       '.*zip.*'
	   Matches any package name containing the string zip. Note the	dots:
	   '*zip*' does	not work, because in a regular expression, the
	   character * is interpreted as a quantifier.

       '.*(firefox|chromium).*'
	   Matches any package name containing the strings firefox or
	   chromium.

COMMON OPTIONS
       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.

       --file /	-f path
	   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.

	   If the argument starts with http:// or https://, it is interpreted
	   as the URL of a tarball that	will be	downloaded and unpacked	to a
	   temporary location. The tarball must	include	a single top-level
	   directory containing	at least a file	named default.nix.

       --profile / -p path
	   Specifies the profile to be used by those operations	that operate
	   on a	profile	(designated below as the active	profile). A profile is
	   a sequence of user environments called generations, one of which is
	   the current generation.

       --dry-run
	   For the --install, --upgrade, --uninstall, --switch-generation,
	   --delete-generations	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.

	   --dry-run also prints out which paths will be substituted (i.e.,
	   downloaded) and which paths will be built from source (because no
	   substitute is available).

       --system-filter system
	   By default, operations such as --query --available show derivations
	   matching any	platform. This option allows you to use	derivations
	   for the specified platform system.

       --help
	   Prints out a	summary	of the command syntax and exits.

       --version
	   Prints out the Nix version number on	standard output	and exits.

       --verbose / -v
	   Increases the level of verbosity of diagnostic messages printed on
	   standard error. For each Nix	operation, the information printed on
	   standard output is well-defined; any	diagnostic information is
	   printed on standard error, never on standard	output.

	   This	option may be specified	repeatedly. Currently, the following
	   verbosity levels exist:

	   0
	       "Errors only": only print messages explaining why the Nix
	       invocation failed.

	   1
	       "Informational":	print useful messages about what Nix is	doing.
	       This is the default.

	   2
	       "Talkative": print more informational messages.

	   3
	       "Chatty": print even more informational messages.

	   4
	       "Debug":	print debug information.

	   5
	       "Vomit":	print vast amounts of debug information.

       --quiet
	   Decreases the level of verbosity of diagnostic messages printed on
	   standard error. This	is the inverse option to -v / --verbose.

	   This	option may be specified	repeatedly. See	the previous verbosity
	   levels list.

       --no-build-output / -Q
	   By default, output written by builders to standard output and
	   standard error is echoed to the Nix command's standard error. This
	   option suppresses this behaviour. Note that the builder's standard
	   output and error are	always written to a log	file in
	   prefix/nix/var/log/nix.

       --max-jobs / -j number
	   Sets	the maximum number of build jobs that Nix will perform in
	   parallel to the specified number. Specify auto to use the number of
	   CPUs	in the system. The default is specified	by the max-jobs
	   configuration setting, which	itself defaults	to 1. A	higher value
	   is useful on	SMP systems or to exploit I/O latency.

	   Setting it to 0 disallows building on the local machine, which is
	   useful when you want	builds to happen only on remote	builders.

       --cores
	   Sets	the value of the NIX_BUILD_CORES environment variable in the
	   invocation of builders. Builders can	use this variable at their
	   discretion to control the maximum amount of parallelism. For
	   instance, in	Nixpkgs, if the	derivation attribute
	   enableParallelBuilding is set to true, the builder passes the -jN
	   flag	to GNU Make. It	defaults to the	value of the cores
	   configuration setting, if set, or 1 otherwise. The value 0 means
	   that	the builder should use all available CPU cores in the system.

       --max-silent-time
	   Sets	the maximum number of seconds that a builder can go without
	   producing any data on standard output or standard error. The
	   default is specified	by the max-silent-time configuration setting.
	   0 means no time-out.

       --timeout
	   Sets	the maximum number of seconds that a builder can run. The
	   default is specified	by the timeout configuration setting.  0 means
	   no timeout.

       --keep-going / -k
	   Keep	going in case of failed	builds,	to the greatest	extent
	   possible. That is, if building an input of some derivation fails,
	   Nix will still build	the other inputs, but not the derivation
	   itself. Without this	option,	Nix stops if any build fails (except
	   for builds of substitutes), possibly	killing	builds in progress (in
	   case	of parallel or distributed builds).

       --keep-failed / -K
	   Specifies that in case of a build failure, the temporary directory
	   (usually in /tmp) in	which the build	takes place should not be
	   deleted. The	path of	the build directory is printed as an
	   informational message.

       --fallback
	   Whenever Nix	attempts to build a derivation for which substitutes
	   are known for each output path, but realising the output paths
	   through the substitutes fails, fall back on building	the
	   derivation.

	   The most common scenario in which this is useful is when we have
	   registered substitutes in order to perform binary distribution
	   from, say, a	network	repository. If the repository is down, the
	   realisation of the derivation will fail. When this option is
	   specified, Nix will build the derivation instead. Thus,
	   installation	from binaries falls back on installation from source.
	   This	option is not the default since	it is generally	not desirable
	   for a transient failure in obtaining	the substitutes	to lead	to a
	   full	build from source (with	the related consumption	of resources).

       --no-build-hook
	   Disables the	build hook mechanism. This allows to ignore remote
	   builders if they are	setup on the machine.

	   It's	useful in cases	where the bandwidth between the	client and the
	   remote builder is too low. In that case it can take more time to
	   upload the sources to the remote builder and	fetch back the result
	   than	to do the computation locally.

       --readonly-mode
	   When	this option is used, no	attempt	is made	to open	the Nix
	   database. Most Nix operations do need database access, so those
	   operations will fail.

       --arg name value
	   This	option is accepted by nix-env, nix-instantiate and nix-build.
	   When	evaluating Nix expressions, the	expression evaluator will
	   automatically try to	call functions that it encounters. It can
	   automatically call functions	for which every	argument has a default
	   value (e.g.,	{ argName ? defaultValue }: ...). With --arg, you can
	   also	call functions that have arguments without a default value (or
	   override a default value). That is, if the evaluator	encounters a
	   function with an argument named name, it will call it with value
	   value.

	   For instance, the top-level default.nix in Nixpkgs is actually a
	   function:

	       { # The system (e.g., `i686-linux') for which to	build the packages.
		 system	? builtins.currentSystem
		 ...
	       }: ...

	   So if you call this Nix expression (e.g., when you do nix-env -i
	   pkgname), the function will be called automatically using the value
	   builtins.currentSystem for the system argument. You can override
	   this	using --arg, e.g., nix-env -i pkgname --arg system
	   \"i686-freebsd\". (Note that	since the argument is a	Nix string
	   literal, you	have to	escape the quotes.)

       --argstr	name value
	   This	option is like --arg, only the value is	not a Nix expression
	   but a string. So instead of --arg system \"i686-linux\" (the	outer
	   quotes are to keep the shell	happy) you can say --argstr system
	   i686-linux.

       --attr /	-A attrPath
	   Select an attribute from the	top-level Nix expression being
	   evaluated. (nix-env,	nix-instantiate, nix-build and nix-shell
	   only.) The attribute	path attrPath is a sequence of attribute names
	   separated by	dots. For instance, given a top-level Nix expression
	   e, the attribute path xorg.xorgserver would cause the expression
	   e.xorg.xorgserver to	be used. See nix-env --install for some
	   concrete examples.

	   In addition to attribute names, you can also	specify	array indices.
	   For instance, the attribute path foo.3.bar selects the bar
	   attribute of	the fourth element of the array	in the foo attribute
	   of the top-level expression.

       --expr /	-E
	   Interpret the command line arguments	as a list of Nix expressions
	   to be parsed	and evaluated, rather than as a	list of	file names of
	   Nix expressions. (nix-instantiate, nix-build	and nix-shell only.)

       -I path
	   Add a path to the Nix expression search path. This option may be
	   given multiple times. See the NIX_PATH environment variable for
	   information on the semantics	of the Nix search path.	Paths added
	   through -I take precedence over NIX_PATH.

       --option	name value
	   Set the Nix configuration option name to value. This	overrides
	   settings in the Nix configuration file (see nix.conf(5)).

       --repair
	   Fix corrupted or missing store paths	by redownloading or rebuilding
	   them. Note that this	is slow	because	it requires computing a
	   cryptographic hash of the contents of every path in the closure of
	   the build. Also note	the warning under nix-store --repair-path.

FILES
       ~/.nix-defexpr
	   The source for the default Nix expressions used by the --install,
	   --upgrade, and --query --available operations to obtain
	   derivations.	The --file option may be used to override this
	   default.

	   If ~/.nix-defexpr is	a file,	it is loaded as	a Nix expression. If
	   the expression is a set, it is used as the default Nix expression.
	   If the expression is	a function, an empty set is passed as argument
	   and the return value	is used	as the default Nix expression.

	   If ~/.nix-defexpr is	a directory containing a default.nix file,
	   that	file is	loaded as in the above paragraph.

	   If ~/.nix-defexpr is	a directory without a default.nix file,	then
	   its contents	(both files and	subdirectories)	are loaded as Nix
	   expressions.	The expressions	are combined into a single set,	each
	   expression under an attribute with the same name as the original
	   file	or subdirectory.

	   For example,	if ~/.nix-defexpr contains two files, foo.nix and
	   bar.nix, then the default Nix expression will essentially be

	       {
		 foo = import ~/.nix-defexpr/foo.nix;
		 bar = import ~/.nix-defexpr/bar.nix;
	       }

	   The file manifest.nix is always ignored. Subdirectories without a
	   default.nix file are	traversed recursively in search	of more	Nix
	   expressions,	but the	names of these intermediate directories	are
	   not added to	the attribute paths of the default Nix expression.

	   The command nix-channel places symlinks to the downloaded Nix
	   expressions from each subscribed channel in this directory.

       ~/.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.

OPERATION --INSTALL
   Synopsis
       nix-env {--install | -i}	[{--prebuilt-only | -b}] [{--attr | -A}]
	       [--from-expression] [-E]	[--from-profile	path]
	       [--preserve-installed | -P] [--remove-all | -r] args...

   Description
       The install operation creates a new user	environment, based on the
       current generation of the active	profile, to which a set	of store paths
       described by args is added. The arguments args map to store paths in a
       number of possible ways:

       o   By default, args is a set of	derivation names denoting derivations
	   in the active Nix expression. These are realised, and the resulting
	   output paths	are installed. Currently installed derivations with a
	   name	equal to the name of a derivation being	added are removed
	   unless the option --preserve-installed is specified.

	   If there are	multiple derivations matching a	name in	args that have
	   the same name (e.g.,	gcc-3.3.6 and gcc-4.1.1), then the derivation
	   with	the highest priority is	used. A	derivation can define a
	   priority by declaring the meta.priority attribute. This attribute
	   should be a number, with a higher value denoting a lower priority.
	   The default priority	is 0.

	   If there are	multiple matching derivations with the same priority,
	   then	the derivation with the	highest	version	will be	installed.

	   You can force the installation of multiple derivations with the
	   same	name by	being specific about the versions. For instance,
	   nix-env -i gcc-3.3.6	gcc-4.1.1 will install both version of GCC
	   (and	will probably cause a user environment conflict!).

       o   If --attr (-A) is specified,	the arguments are attribute paths that
	   select attributes from the top-level	Nix expression.	This is	faster
	   than	using derivation names and unambiguous.	To find	out the
	   attribute paths of available	packages, use nix-env -qaP.

       o   If --from-profile path is given, args is a set of names denoting
	   installed store paths in the	profile	path. This is an easy way to
	   copy	user environment elements from one profile to another.

       o   If --from-expression	is given, args are Nix functions that are
	   called with the active Nix expression as their single argument. The
	   derivations returned	by those function calls	are installed. This
	   allows derivations to be specified in an unambiguous	way, which is
	   necessary if	there are multiple derivations with the	same name.

       o   If args are store derivations, then these are realised, and the
	   resulting output paths are installed.

       o   If args are store paths that	are not	store derivations, then	these
	   are realised	and installed.

       o   By default all outputs are installed	for each derivation. That can
	   be reduced by setting meta.outputsToInstall.

   Flags
       --prebuilt-only / -b
	   Use only derivations	for which a substitute is registered, i.e.,
	   there is a pre-built	binary available that can be downloaded	in
	   lieu	of building the	derivation. Thus, no packages will be built
	   from	source.

       --preserve-installed, -P
	   Do not remove derivations with a name matching one of the
	   derivations being installed.	Usually, trying	to have	two versions
	   of the same package installed in the	same generation	of a profile
	   will	lead to	an error in building the generation, due to file name
	   clashes between the two versions. However, this is not the case for
	   all packages.

       --remove-all, -r
	   Remove all previously installed packages first. This	is equivalent
	   to running nix-env -e '.*' first, except that everything happens in
	   a single transaction.

   Examples
       To install a specific version of	gcc from the active Nix	expression:

	   $ nix-env --install gcc-3.3.2
	   installing `gcc-3.3.2'
	   uninstalling	`gcc-3.1'

       Note the	previously installed version is	removed, since
       --preserve-installed was	not specified.

       To install an arbitrary version:

	   $ nix-env --install gcc
	   installing `gcc-3.3.2'

       To install using	a specific attribute:

	   $ nix-env -i	-A gcc40mips
	   $ nix-env -i	-A xorg.xorgserver

       To install all derivations in the Nix expression	foo.nix:

	   $ nix-env -f	~/foo.nix -i '.*'

       To copy the store path with symbolic name gcc from another profile:

	   $ nix-env -i	--from-profile /nix/var/nix/profiles/foo gcc

       To install a specific store derivation (typically created by
       nix-instantiate):

	   $ nix-env -i	/nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv

       To install a specific output path:

	   $ nix-env -i	/nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3

       To install from a Nix expression	specified on the command-line:

	   $ nix-env -f	./foo.nix -i -E	\
	       'f: (f {system =	"i686-linux";}).subversionWithJava'

       I.e., this evaluates to (f: (f {system =
       "i686-linux";}).subversionWithJava) (import ./foo.nix), thus selecting
       the subversionWithJava attribute	from the set returned by calling the
       function	defined	in ./foo.nix.

       A dry-run tells you which paths will be downloaded or built from
       source:

	   $ nix-env -f	'<nixpkgs>' -iA	hello --dry-run
	   (dry	run; not doing anything)
	   installing `hello-2.10'
	   these paths will be fetched (0.04 MiB download, 0.19	MiB unpacked):
	     /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
	     ...

       To install Firefox from the latest revision in the Nixpkgs/NixOS	14.12
       channel:

	   $ nix-env -f	https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox

       (The GitHub repository nixpkgs-channels is updated automatically	from
       the main	nixpkgs	repository after certain tests have succeeded and
       binaries	have been built	and uploaded to	the binary cache at
       cache.nixos.org.)

OPERATION --UPGRADE
   Synopsis
       nix-env {--upgrade | -u}	[{--prebuilt-only | -b}] [{--attr | -A}]
	       [--from-expression] [-E]	[--from-profile	path] [--lt | --leq |
	       --eq | --always]	args...

   Description
       The upgrade operation creates a new user	environment, based on the
       current generation of the active	profile, in which all store paths are
       replaced	for which there	are newer versions in the set of paths
       described by args. Paths	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 args matches no installed derivations.

       For a description of how	args is	mapped to a set	of store paths,	see
       --install. If args describes multiple store paths with the same
       symbolic	name, only the one with	the highest version is installed.

   Flags
       --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.

       --eq
	   Only	"upgrade" to derivations that have the same version. This may
	   not seem very useful, but it	actually is, e.g., when	there is a new
	   release of Nixpkgs and you want to replace installed	applications
	   with	the same versions built	against	newer dependencies (to reduce
	   the number of dependencies floating around on your system).

       --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.

       For the other flags, see	--install.

   Examples
	   $ 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'

   Versions
       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	followed 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

OPERATION --UNINSTALL
   Synopsis
       nix-env {--uninstall | -e} drvnames...

   Description
       The uninstall operation creates a new user environment, based on	the
       current generation of the active	profile, from which the	store paths
       designated by the symbolic names	names are removed.

   Examples
	   $ nix-env --uninstall gcc
	   $ nix-env -e	'.*' (remove everything)

OPERATION --SET
   Synopsis
       nix-env --set drvname

   Description
       The --set operation modifies the	current	generation of a	profile	so
       that it contains	exactly	the specified derivation, and nothing else.

   Examples
       The following updates a profile such that its current generation	will
       contain just Firefox:

	   $ nix-env -p	/nix/var/nix/profiles/browser --set firefox

OPERATION --SET-FLAG
   Synopsis
       nix-env --set-flag name value drvnames...

   Description
       The --set-flag operation	allows meta attributes of installed packages
       to be modified. There are several attributes that can be	usefully
       modified, because they affect the behaviour of nix-env or the user
       environment build script:

       o   priority can	be changed to resolve filename clashes.	The user
	   environment build script uses the meta.priority attribute of
	   derivations to resolve filename collisions between packages.	Lower
	   priority values denote a higher priority. For instance, the GCC
	   wrapper package and the Binutils package in Nixpkgs both have a
	   file	bin/ld,	so previously if you tried to install both you would
	   get a collision. Now, on the	other hand, the	GCC wrapper declares a
	   higher priority than	Binutils, so the former's bin/ld is symlinked
	   in the user environment.

       o   keep	can be set to true to prevent the package from being upgraded
	   or replaced.	This is	useful if you want to hang on to an older
	   version of a	package.

       o   active can be set to	false to "disable" the package.	That is, no
	   symlinks will be generated to the files of the package, but it
	   remains part	of the profile (so it won't be garbage-collected). It
	   can be set back to true to re-enable	the package.

   Examples
       To prevent the currently	installed Firefox from being upgraded:

	   $ nix-env --set-flag	keep true firefox

       After this, nix-env -u will ignore Firefox.

       To disable the currently	installed Firefox, then	install	a new Firefox
       while the old remains part of the profile:

	   $ nix-env -q
	   firefox-2.0.0.9 (the	current	one)

	   $ nix-env --preserve-installed -i firefox-2.0.0.11
	   installing `firefox-2.0.0.11'
	   building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
	   collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
	     and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
	   (i.e., can't	have two active	at the same time)

	   $ nix-env --set-flag	active false firefox
	   setting flag	on `firefox-2.0.0.9'

	   $ nix-env --preserve-installed -i firefox-2.0.0.11
	   installing `firefox-2.0.0.11'

	   $ nix-env -q
	   firefox-2.0.0.11 (the enabled one)
	   firefox-2.0.0.9 (the	disabled one)

       To make files from binutils take	precedence over	files from gcc:

	   $ nix-env --set-flag	priority 5 binutils
	   $ nix-env --set-flag	priority 10 gcc

OPERATION --QUERY
   Synopsis
       nix-env {--query	| -q} [--installed | --available | -a]
	       [{--status | -s}] [{--attr-path | -P}] [--no-name]
	       [{--compare-versions | -c}] [--system] [--drv-path]
	       [--out-path] [--description] [--meta]
	       [--xml] [--json]	[{--prebuilt-only | -b}]
	       [{--attr	| -A} attribute-path]
	       names...

   Description
       The query operation displays information	about either the store paths
       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). It only prints information
       about derivations whose symbolic	name matches one of names.

       The derivations are sorted by their name	attributes.

   Source selection
       The following flags specify the set of things on	which the query
       operates.

       --installed
	   The query operates on the store paths 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.

   Queries
       The following flags specify what	information to display about the
       selected	derivations. Multiple flags may	be specified, in which case
       the information is shown	in the order given here. Note that the name of
       the derivation is shown unless --no-name	is specified.

       --xml
	   Print the result in an XML representation suitable for automatic
	   processing by other tools. The root element is called items,	which
	   contains a item element for each available or installed derivation.
	   The fields discussed	below are all stored in	attributes of the item
	   elements.

       --json
	   Print the result in a JSON representation suitable for automatic
	   processing by other tools.

       --prebuilt-only / -b
	   Show	only derivations for which a substitute	is registered, i.e.,
	   there is a pre-built	binary available that can be downloaded	in
	   lieu	of building the	derivation. Thus, this shows all packages that
	   probably can	be installed quickly.

       --status, -s
	   Print the status of the derivation. 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.

       --attr-path, -P
	   Print the attribute path of the derivation, which can be used to
	   unambiguously select	it using the --attr option available in
	   commands that install derivations like nix-env --install.

       --no-name
	   Suppress printing of	the name attribute of each derivation.

       --compare-versions / -c
	   Compare installed versions to available versions, or	vice versa (if
	   --available is given). This is useful for quickly seeing whether
	   upgrades for	installed packages are available in a Nix expression.
	   A column is added with the following	meaning:

	   < version
	       A newer version of the package is available or installed.

	   = version
	       At most the same	version	of the package is available or
	       installed.

	   > version
	       Only older versions of the package are available	or installed.

	   - ?
	       No version of the package is available or installed.

       --system
	   Print the system attribute of the derivation.

       --drv-path
	   Print the path of the store derivation.

       --out-path
	   Print the output path of the	derivation.

       --description
	   Print a short (one-line) description	of the derivation, if
	   available. The description is taken from the	meta.description
	   attribute of	the derivation.

       --meta
	   Print all of	the meta-attributes of the derivation. This option is
	   only	available with --xml or	--json.

   Examples
       To show installed packages:

	   $ nix-env -q
	   bison-1.875c
	   docbook-xml-4.2
	   firefox-1.0.4
	   MPlayer-1.0pre7
	   ORBit2-2.8.3
	   ...

       To show available packages:

	   $ nix-env -qa
	   firefox-1.0.7
	   GConf-2.4.0.1
	   MPlayer-1.0pre7
	   ORBit2-2.8.3
	   ...

       To show the status of available packages:

	   $ nix-env -qas
	   -P- firefox-1.0.7   (not installed but present)
	   --S GConf-2.4.0.1   (not present, but there is a substitute for fast	installation)
	   --S MPlayer-1.0pre3 (i.e., this is not the installed	MPlayer, even though the version is the	same!)
	   IP- ORBit2-2.8.3    (installed and by definition present)
	   ...

       To show available packages in the Nix expression	foo.nix:

	   $ nix-env -f	./foo.nix -qa
	   foo-1.2.3

       To compare installed versions to	what's available:

	   $ nix-env -qc
	   ...
	   acrobat-reader-7.0 -	?      (package	is not available at all)
	   autoconf-2.59      =	2.59   (same version)
	   firefox-1.0.4      <	1.0.7  (a more recent version is available)
	   ...

       To show all packages with "zip" in the name:

	   $ nix-env -qa '.*zip.*'
	   bzip2-1.0.6
	   gzip-1.6
	   zip-3.0
	   ...

       To show all packages with "firefox" or "chromium" in the	name:

	   $ nix-env -qa '.*(firefox|chromium).*'
	   chromium-37.0.2062.94
	   chromium-beta-38.0.2125.24
	   firefox-32.0.3
	   firefox-with-plugins-13.0.1
	   ...

       To show all packages in the latest revision of the Nixpkgs repository:

	   $ nix-env -f	https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa

OPERATION --SWITCH-PROFILE
   Synopsis
       nix-env {--switch-profile | -S} {path}

   Description
       This operation makes path the current profile for the user. That	is,
       the symlink ~/.nix-profile is made to point to path.

   Examples
	   $ nix-env -S	~/my-profile

OPERATION --LIST-GENERATIONS
   Synopsis
       nix-env --list-generations

   Description
       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.

   Examples
	   $ 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)

OPERATION --DELETE-GENERATIONS
   Synopsis
       nix-env --delete-generations generations...

   Description
       This operation deletes the specified generations	of the current
       profile.	The generations	can be a list of generation numbers, the
       special value old to delete all non-current generations,	a value	such
       as 30d to delete	all generations	older than the specified number	of
       days (except for	the generation that was	active at that point in	time),
       or a value such as +5 to	keep the last 5	generations ignoring any newer
       than current, e.g., if 30 is the	current	generation +5 will delete
       generation 25 and all older generations.	Periodically deleting old
       generations is important	to make	garbage	collection effective.

   Examples
	   $ nix-env --delete-generations 3 4 8

	   $ nix-env --delete-generations +5

	   $ nix-env --delete-generations 30d

	   $ nix-env -p	other_profile --delete-generations old

OPERATION --SWITCH-GENERATION
   Synopsis
       nix-env {--switch-generation | -G} {generation}

   Description
       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.

   Examples
	   $ nix-env -G	42
	   switching from generation 50	to 42

OPERATION --ROLLBACK
   Synopsis
       nix-env --rollback

   Description
       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.

   Examples
	   $ nix-env --rollback
	   switching from generation 92	to 91

	   $ nix-env --rollback
	   error: no generation	older than the current (91) exists

ENVIRONMENT VARIABLES
       NIX_PROFILE
	   Location of the Nix profile.	Defaults to the	target of the symlink
	   ~/.nix-profile, if it exists, or /nix/var/nix/profiles/default
	   otherwise.

       IN_NIX_SHELL
	   Indicator that tells	if the current environment was set up by
	   nix-shell. Since Nix	2.0 the	values are "pure" and "impure"

       NIX_PATH
	   A colon-separated list of directories used to look up Nix
	   expressions enclosed	in angle brackets (i.e., <path>). For
	   instance, the value

	       /home/eelco/Dev:/etc/nixos

	   will	cause Nix to look for paths relative to	/home/eelco/Dev	and
	   /etc/nixos, in that order. It is also possible to match paths
	   against a prefix. For example, the value

	       nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos

	   will	cause Nix to search for	<nixpkgs/path> in
	   /home/eelco/Dev/nixpkgs-branch/path and /etc/nixos/nixpkgs/path.

	   If a	path in	the Nix	search path starts with	http://	or https://,
	   it is interpreted as	the URL	of a tarball that will be downloaded
	   and unpacked	to a temporary location. The tarball must consist of a
	   single top-level directory. For example, setting NIX_PATH to

	       nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-15.09.tar.gz

	   tells Nix to	download the latest revision in	the Nixpkgs/NixOS
	   15.09 channel.

	   A following shorthand can be	used to	refer to the official
	   channels:

	       nixpkgs=channel:nixos-15.09

	   The search path can be extended using the -I	option,	which takes
	   precedence over NIX_PATH.

       NIX_IGNORE_SYMLINK_STORE
	   Normally, the Nix store directory (typically	/nix/store) is not
	   allowed to contain any symlink components. This is to prevent
	   "impure" builds. Builders sometimes "canonicalise" paths by
	   resolving all symlink components. Thus, builds on different
	   machines (with /nix/store resolving to different locations) could
	   yield different results. This is generally not a problem, except
	   when	builds are deployed to machines	where /nix/store resolves
	   differently.	If you are sure	that you're not	going to do that, you
	   can set NIX_IGNORE_SYMLINK_STORE to 1.

	   Note	that if	you're symlinking the Nix store	so that	you can	put it
	   on another file system than the root	file system, on	Linux you're
	   better off using bind mount points, e.g.,

	       $ mkdir /nix
	       $ mount -o bind /mnt/otherdisk/nix /nix

	   Consult the mount(8)	manual page for	details.

       NIX_STORE_DIR
	   Overrides the location of the Nix store (default prefix/store).

       NIX_DATA_DIR
	   Overrides the location of the Nix static data directory (default
	   prefix/share).

       NIX_LOG_DIR
	   Overrides the location of the Nix log directory (default
	   prefix/var/log/nix).

       NIX_STATE_DIR
	   Overrides the location of the Nix state directory (default
	   prefix/var/nix).

       NIX_CONF_DIR
	   Overrides the location of the Nix configuration directory (default
	   prefix/etc/nix).

       TMPDIR
	   Use the specified directory to store	temporary files. In
	   particular, this includes temporary build directories; these	can
	   take	up substantial amounts of disk space. The default is /tmp.

       NIX_REMOTE
	   This	variable should	be set to daemon if you	want to	use the	Nix
	   daemon to execute Nix operations. This is necessary in multi-user
	   Nix installations. If the Nix daemon's Unix socket is at some
	   non-standard	path, this variable should be set to
	   unix://path/to/socket. Otherwise, it	should be left unset.

       NIX_SHOW_STATS
	   If set to 1,	Nix will print some evaluation statistics, such	as the
	   number of values allocated.

       NIX_COUNT_CALLS
	   If set to 1,	Nix will print how often functions were	called during
	   Nix expression evaluation. This is useful for profiling your	Nix
	   expressions.

       GC_INITIAL_HEAP_SIZE
	   If Nix has been configured to use the Boehm garbage collector, this
	   variable sets the initial size of the heap in bytes.	It defaults to
	   384 MiB. Setting it to a low	value reduces memory consumption, but
	   will	increase runtime due to	the overhead of	garbage	collection.

AUTHOR
       Eelco Dolstra
	   Author

COPYRIGHT
       Copyright (C) 2004-2018 Eelco Dolstra

Nix 2.3.10			  03/02/2021			    NIX-ENV(1)

NAME | SYNOPSIS | DESCRIPTION | SELECTORS | COMMON OPTIONS | FILES | OPERATION --INSTALL | OPERATION --UPGRADE | OPERATION --UNINSTALL | OPERATION --SET | OPERATION --SET-FLAG | OPERATION --QUERY | OPERATION --SWITCH-PROFILE | OPERATION --LIST-GENERATIONS | OPERATION --DELETE-GENERATIONS | OPERATION --SWITCH-GENERATION | OPERATION --ROLLBACK | ENVIRONMENT VARIABLES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nix-env&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help