path: root/doc/manual/installation/installing-binary.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="ch-installing-binary">

<title>Installing a Binary Distribution</title>

<para>
  If you are using Linux or macOS versions up to 10.14 (Mojave), the
  easiest way to install Nix is to run the following command:
</para>

<screen>
  $ sh &lt;(curl -L https://nixos.org/nix/install)
</screen>

<para>
  If you're using macOS 10.15 (Catalina) or newer, consult
  <link linkend="sect-macos-installation">the macOS installation instructions</link>
  before installing.
</para>

<para>
  As of Nix 2.1.0, the Nix installer will always default to creating a
  single-user installation, however opting in to the multi-user
  installation is highly recommended.
  <!-- TODO: this explains *neither* why the default version is
  single-user, nor why we'd recommend multi-user over the default.
  True prospective users don't have much basis for evaluating this.
  What's it to me? Who should pick which? Why? What if I pick wrong?
  -->
</para>

<section xml:id="sect-single-user-installation">
  <title>Single User Installation</title>

  <para>
    To explicitly select a single-user installation on your system:

    <screen>
  sh &lt;(curl -L https://nixos.org/nix/install) --no-daemon
</screen>
  </para>

<para>
This will perform a single-user installation of Nix, meaning that
<filename>/nix</filename> is owned by the invoking user.  You should
run this under your usual user account, <emphasis>not</emphasis> as
root.  The script will invoke <command>sudo</command> to create
<filename>/nix</filename> if it doesn’t already exist.  If you don’t
have <command>sudo</command>, you should manually create
<filename>/nix</filename> first as root, e.g.:

<screen>
$ mkdir /nix
$ chown alice /nix
</screen>

The install script will modify the first writable file from amongst
<filename>.bash_profile</filename>, <filename>.bash_login</filename>
and <filename>.profile</filename> to source
<filename>~/.nix-profile/etc/profile.d/nix.sh</filename>. You can set
the <literal>NIX_INSTALLER_NO_MODIFY_PROFILE</literal> environment
variable before executing the install script to disable this
behaviour.
</para>


<para>You can uninstall Nix simply by running:

<screen>
$ rm -rf /nix
</screen>

</para>
</section>

<section xml:id="sect-multi-user-installation">
  <title>Multi User Installation</title>
  <para>
    The multi-user Nix installation creates system users, and a system
    service for the Nix daemon.
  </para>

  <itemizedlist>
    <title>Supported Systems</title>

    <listitem>
      <para>Linux running systemd, with SELinux disabled</para>
    </listitem>
    <listitem><para>macOS</para></listitem>
  </itemizedlist>

  <para>
    You can instruct the installer to perform a multi-user
    installation on your system:
  </para>

  <screen>sh &lt;(curl -L https://nixos.org/nix/install) --daemon</screen>

  <para>
    The multi-user installation of Nix will create build users between
    the user IDs 30001 and 30032, and a group with the group ID 30000.

    You should run this under your usual user account,
    <emphasis>not</emphasis> as root. The script will invoke
    <command>sudo</command> as needed.
  </para>

  <note><para>
    If you need Nix to use a different group ID or user ID set, you
    will have to download the tarball manually and <link
    linkend="sect-nix-install-binary-tarball">edit the install
    script</link>.
  </para></note>

  <para>
    The installer will modify <filename>/etc/bashrc</filename>, and
    <filename>/etc/zshrc</filename> if they exist. The installer will
    first back up these files with a
    <literal>.backup-before-nix</literal> extension. The installer
    will also create <filename>/etc/profile.d/nix.sh</filename>.
  </para>

  <para>You can uninstall Nix with the following commands:

<screen>
sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels

# If you are on Linux with systemd, you will need to run:
sudo systemctl stop nix-daemon.socket
sudo systemctl stop nix-daemon.service
sudo systemctl disable nix-daemon.socket
sudo systemctl disable nix-daemon.service
sudo systemctl daemon-reload

# If you are on macOS, you will need to run:
sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist
sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist
</screen>

    There may also be references to Nix in
    <filename>/etc/profile</filename>,
    <filename>/etc/bashrc</filename>, and
    <filename>/etc/zshrc</filename> which you may remove.
  </para>

</section>

<section xml:id="sect-macos-installation">
  <title>macOS Installation</title>

  <para>
    Starting with macOS 10.15 (Catalina), the root filesystem is read-only.
    This means <filename>/nix</filename> can no longer live on your system
    volume, and that you'll need a workaround to install Nix.
  </para>

  <para>
    The recommended approach, which creates an unencrypted APFS volume
    for your Nix store and a "synthetic" empty directory to mount it
    over at <filename>/nix</filename>, is least likely to impair Nix
    or your system.
  </para>

  <note><para>
    With all separate-volume approaches, it's possible something on
    your system (particularly daemons/services and restored apps) may
    need access to your Nix store before the volume is mounted. Adding
    additional encryption makes this more likely.
  </para></note>

  <para>
    If you're using a recent Mac with a
    <link xlink:href="https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf">T2 chip</link>,
    your drive will still be encrypted at rest (in which case "unencrypted"
    is a bit of a misnomer). To use this approach, just install Nix with:
  </para>

  <screen>$ sh &lt;(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume</screen>

  <para>
    If you don't like the sound of this, you'll want to weigh the
    other approaches and tradeoffs detailed in this section.
  </para>

  <note>
    <title>Eventual solutions?</title>
    <para>
      All of the known workarounds have drawbacks, but we hope
      better solutions will be available in the future. Some that
      we have our eye on are:
    </para>
    <orderedlist>
      <listitem>
        <para>
          A true firmlink would enable the Nix store to live on the
          primary data volume without the build problems caused by
          the symlink approach. End users cannot currently
          create true firmlinks.
        </para>
      </listitem>
      <listitem>
        <para>
          If the Nix store volume shared FileVault encryption
          with the primary data volume (probably by using the same
          volume group and role), FileVault encryption could be
          easily supported by the installer without requiring
          manual setup by each user.
        </para>
      </listitem>
    </orderedlist>
  </note>

  <section xml:id="sect-macos-installation-change-store-prefix">
    <title>Change the Nix store path prefix</title>
    <para>
      Changing the default prefix for the Nix store is a simple
      approach which enables you to leave it on your root volume,
      where it can take full advantage of FileVault encryption if
      enabled. Unfortunately, this approach also opts your device out
      of some benefits that are enabled by using the same prefix
      across systems:

      <itemizedlist>
        <listitem>
          <para>
            Your system won't be able to take advantage of the binary
            cache (unless someone is able to stand up and support
            duplicate caching infrastructure), which means you'll
            spend more time waiting for builds.
          </para>
        </listitem>
        <listitem>
          <para>
            It's harder to build and deploy packages to Linux systems.
          </para>
        </listitem>
        <!-- TODO: may be more here -->
      </itemizedlist>

      <!-- TODO: Yes, but how?! -->

      It would also possible (and often requested) to just apply this
      change ecosystem-wide, but it's an intrusive process that has
      side effects we want to avoid for now.
      <!-- magnificent hand-wavy gesture -->
    </para>
    <para>
    </para>
  </section>

  <section xml:id="sect-macos-installation-encrypted-volume">
    <title>Use a separate encrypted volume</title>
    <para>
      If you like, you can also add encryption to the recommended
      approach taken by the installer. You can do this by pre-creating
      an encrypted volume before you run the installer--or you can
      run the installer and encrypt the volume it creates later.
      <!-- TODO: see later note about whether this needs both add-encryption and from-scratch directions -->
    </para>
    <para>
      In either case, adding encryption to a second volume isn't quite
      as simple as enabling FileVault for your boot volume. Before you
      dive in, there are a few things to weigh:
    </para>
    <orderedlist>
      <listitem>
        <para>
          The additional volume won't be encrypted with your existing
          FileVault key, so you'll need another mechanism to decrypt
          the volume.
        </para>
      </listitem>
      <listitem>
        <para>
          You can store the password in Keychain to automatically
          decrypt the volume on boot--but it'll have to wait on Keychain
          and may not mount before your GUI apps restore. If any of
          your launchd agents or apps depend on Nix-installed software
          (for example, if you use a Nix-installed login shell), the
          restore may fail or break.
        </para>
        <para>
          On a case-by-case basis, you may be able to work around this
          problem by using <command>wait4path</command> to block
          execution until your executable is available.
        </para>
        <para>
          It's also possible to decrypt and mount the volume earlier
          with a login hook--but this mechanism appears to be
          deprecated and its future is unclear.
        </para>
      </listitem>
      <listitem>
        <para>
          You can hard-code the password in the clear, so that your
          store volume can be decrypted before Keychain is available.
        </para>
      </listitem>
    </orderedlist>
    <para>
      If you are comfortable navigating these tradeoffs, you can encrypt the volume with
      something along the lines of:
      <!-- TODO:
      I don't know if this also needs from-scratch instructions?
      can we just recommend use-the-installer-and-then-encrypt?
      -->
    </para>
    <!--
    TODO: it looks like this option can be encryptVolume|encrypt|enableFileVault

    It may be more clear to use encryptVolume, here? FileVault seems
    heavily associated with the boot-volume behavior; I worry
    a little that it can mislead here, especially as it gets
    copied around minus doc context...?
    -->
    <screen>alice$ diskutil apfs enableFileVault /nix -user disk</screen>

    <!-- TODO: and then go into detail on the mount/decrypt approaches? -->
  </section>

  <section xml:id="sect-macos-installation-symlink">
    <!--
    Maybe a good razor is: if we'd hate having to support someone who
    installed Nix this way, it shouldn't even be detailed?
    -->
    <title>Symlink the Nix store to a custom location</title>
    <para>
      Another simple approach is using <filename>/etc/synthetic.conf</filename>
      to symlink the Nix store to the data volume. This option also
      enables your store to share any configured FileVault encryption.
      Unfortunately, builds that resolve the symlink may leak the
      canonical path or even fail.
    </para>
    <para>
      Because of these downsides, we can't recommend this approach.
    </para>
    <!-- Leaving out instructions for this one. -->
  </section>

  <section xml:id="sect-macos-installation-recommended-notes">
    <title>Notes on the recommended approach</title>
    <para>
      This section goes into a little more detail on the recommended
      approach. You don't need to understand it to run the installer,
      but it can serve as a helpful reference if you run into trouble.
    </para>
    <orderedlist>
      <listitem>
        <para>
          In order to compose user-writable locations into the new
          read-only system root, Apple introduced a new concept called
          <literal>firmlinks</literal>, which it describes as a
          "bi-directional wormhole" between two filesystems. You can
          see the current firmlinks in <filename>/usr/share/firmlinks</filename>.
          Unfortunately, firmlinks aren't (currently?) user-configurable.
        </para>

        <para>
          For special cases like NFS mount points or package manager roots,
          <link xlink:href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html">synthetic.conf(5)</link>
          supports limited user-controlled file-creation (of symlinks,
          and synthetic empty directories) at <filename>/</filename>.
          To create a synthetic empty directory for mounting at <filename>/nix</filename>,
          add the following line to <filename>/etc/synthetic.conf</filename>
          (create it if necessary):
        </para>

        <screen>nix</screen>
      </listitem>

      <listitem>
        <para>
          This configuration is applied at boot time, but you can use
          <command>apfs.util</command> to trigger creation (not deletion)
          of new entries without a reboot:
        </para>

        <screen>alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B</screen>
      </listitem>

      <listitem>
        <para>
          Create the new APFS volume with diskutil:
        </para>

        <screen>alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix</screen>
      </listitem>

      <listitem>
        <para>
          Using <command>vifs</command>, add the new mount to
          <filename>/etc/fstab</filename>. If it doesn't already have
          other entries, it should look something like:
        </para>

<screen>
#
# Warning - this file should only be modified with vifs(8)
#
# Failure to do so is unsupported and may be destructive.
#
LABEL=Nix\040Store /nix apfs rw,nobrowse
</screen>

        <para>
          The nobrowse setting will keep Spotlight from indexing this
          volume, and keep it from showing up on your desktop.
        </para>
      </listitem>
    </orderedlist>
  </section>

</section>

<section xml:id="sect-nix-install-pinned-version-url">
  <title>Installing a pinned Nix version from a URL</title>

  <para>
    NixOS.org hosts version-specific installation URLs for all Nix
    versions since 1.11.16, at
    <literal>https://releases.nixos.org/nix/nix-<emphasis>version</emphasis>/install</literal>.
  </para>

  <para>
    These install scripts can be used the same as the main
  NixOS.org installation script:

  <screen>
  sh &lt;(curl -L https://nixos.org/nix/install)
</screen>
  </para>

  <para>
    In the same directory of the install script are sha256 sums, and
    gpg signature files.
  </para>
</section>

<section xml:id="sect-nix-install-binary-tarball">
  <title>Installing from a binary tarball</title>

  <para>
    You can also download a binary tarball that contains Nix and all
    its dependencies.  (This is what the install script at
    <uri>https://nixos.org/nix/install</uri> does automatically.)  You
    should unpack it somewhere (e.g. in <filename>/tmp</filename>),
    and then run the script named <command>install</command> inside
    the binary tarball:


<screen>
alice$ cd /tmp
alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
alice$ cd nix-1.8-x86_64-darwin
alice$ ./install
</screen>
  </para>

  <para>
    If you need to edit the multi-user installation script to use
    different group ID or a different user ID range, modify the
    variables set in the file named
    <filename>install-multi-user</filename>.
  </para>
</section>
</chapter>