path: root/doc/manual/command-ref/env-common.xml

<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-common-env">

<title>Common Environment Variables</title>


<para>Most Nix commands interpret the following environment variables:</para>

<variablelist xml:id="env-common">

<varlistentry><term><envar>IN_NIX_SHELL</envar></term>

  <listitem><para>Indicator that tells if the current environment was set up by
  <command>nix-shell</command>.</para></listitem>

</varlistentry>

<varlistentry xml:id="env-NIX_PATH"><term><envar>NIX_PATH</envar></term>

  <listitem>

    <para>A colon-separated list of directories used to look up Nix
    expressions enclosed in angle brackets (i.e.,
    <literal>&lt;<replaceable>path</replaceable>></literal>).  For
    instance, the value

    <screen>
/home/eelco/Dev:/etc/nixos</screen>

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

    <screen>
nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen>

    will cause Nix to search for
    <literal>&lt;nixpkgs/<replaceable>path</replaceable>></literal> in
    <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename>
    and
    <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para>

    <para>If a path in the Nix search path starts with
    <literal>http://</literal> or <literal>https://</literal>, 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
    <envar>NIX_PATH</envar> to

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

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

    <para>A following shorthand can be used to refer to the official channels:
    
    <screen>nixpkgs=channel:nixos-15.09</screen>
    </para>

    <para>The search path can be extended using the <option
    linkend="opt-I">-I</option> option, which takes precedence over
    <envar>NIX_PATH</envar>.</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term>

  <listitem>

  <para>Normally, the Nix store directory (typically
  <filename>/nix/store</filename>) 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
  <filename>/nix/store</filename> resolving to different locations)
  could yield different results.  This is generally not a problem,
  except when builds are deployed to machines where
  <filename>/nix/store</filename> resolves differently.  If you are
  sure that you’re not going to do that, you can set
  <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para>

  <para>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 <literal>bind</literal> mount points, e.g.,

  <screen>
$ mkdir /nix
$ mount -o bind /mnt/otherdisk/nix /nix</screen>

  Consult the <citerefentry><refentrytitle>mount</refentrytitle>
  <manvolnum>8</manvolnum></citerefentry> manual page for details.</para>

  </listitem>

</varlistentry>


<varlistentry><term><envar>NIX_STORE_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix store (default
  <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_DATA_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix static data
  directory (default
  <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_LOG_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix log directory
  (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_STATE_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix state directory
  (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_CONF_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix configuration
  directory (default
  <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem>

</varlistentry>


<varlistentry><term><envar>TMPDIR</envar></term>

  <listitem><para>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
  <filename>/tmp</filename>.</para></listitem>

</varlistentry>


<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term>

  <listitem><para>This variable should be set to
  <literal>daemon</literal> if you want to use the Nix daemon to
  execute Nix operations. This is necessary in <link
  linkend="ssec-multi-user">multi-user Nix installations</link>.
  If the Nix daemon's Unix socket is at some non-standard path,
  this variable should be set to <literal>unix://path/to/socket</literal>.
  Otherwise, it should be left unset.</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_SHOW_STATS</envar></term>

  <listitem><para>If set to <literal>1</literal>, Nix will print some
  evaluation statistics, such as the number of values
  allocated.</para></listitem>

</varlistentry>


<varlistentry><term><envar>NIX_COUNT_CALLS</envar></term>

  <listitem><para>If set to <literal>1</literal>, Nix will print how
  often functions were called during Nix expression evaluation.  This
  is useful for profiling your Nix expressions.</para></listitem>

</varlistentry>


<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term>

  <listitem><para>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.</para></listitem>

</varlistentry>


</variablelist>


</chapter>