Skip to content

Commit

Permalink
deduplicate installation instructions (#9507)
Browse files Browse the repository at this point in the history 
* deduplicate installation instructions

- reorder sections to present pinned installation more prominently
- remove outdated notes on the macOS installer rework
- update instructions to handle the installer tarball

Co-authored-by: Travis A. Everett <travis.a.everett@gmail.com>
  • Loading branch information
@fricklerhandwerk @abathur
fricklerhandwerk and abathur committed Jan 6, 2024
1 parent a4d33e8 commit 8e865f3
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 80 deletions.
150 changes: 71 additions & 79 deletions doc/manual/src/installation/installing-binary.md
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,111 @@
# Installing a Binary Distribution

The easiest way to install Nix is to run the following command:
To install the latest version Nix, run the following command:

```console
$ curl -L https://nixos.org/nix/install | sh
```

This will run the installer interactively (causing it to explain what
it is doing more explicitly), and perform the default "type" of install
for your platform:
- single-user on Linux
- multi-user on macOS
This performs the default type of installation for your platform:

> **Notes on read-only filesystem root in macOS 10.15 Catalina +**
>
> - It took some time to support this cleanly. You may see posts,
> examples, and tutorials using obsolete workarounds.
> - Supporting it cleanly made macOS installs too complex to qualify
> as single-user, so this type is no longer supported on macOS.
- [Multi-user](#multi-user-installation):
- Linux with systemd and without SELinux
- macOS
- [Single-user](#single-user-installation):
- Linux without systemd
- Linux with SELinux

We recommend the multi-user install if it supports your platform and
you can authenticate with `sudo`.
We recommend the multi-user installation if it supports your platform and you can authenticate with `sudo`.

# Single User Installation

To explicitly select a single-user installation on your system:
The installer can configured with various command line arguments and environment variables.
To show available command line flags:

```console
$ curl -L https://nixos.org/nix/install | sh -s -- --no-daemon
$ curl -L https://nixos.org/nix/install | sh -s -- --help
```

This will perform a single-user installation of Nix, meaning that `/nix`
is owned by the invoking user. You can run this under your usual user
account or root. The script will invoke `sudo` to create `/nix`
if it doesn’t already exist. If you don’t have `sudo`, you should
manually create `/nix` first as root, e.g.:
To check what it does and how it can be customised further, [download and edit the second-stage installation script](#installing-from-a-binary-tarball).

# Installing a pinned Nix version from a URL

Version-specific installation URLs for all Nix versions since 1.11.16 can be found at [releases.nixos.org](https://releases.nixos.org/?prefix=nix/).
The directory for each version contains the corresponding SHA-256 hash.

All installation scripts are invoked the same way:

```console
$ mkdir /nix
$ chown alice /nix
$ export VERSION=2.19.2
$ curl -L https://releases.nixos.org/nix/nix-$VERSION/install | sh
```

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

# Multi User Installation

The multi-user Nix installation creates system users, and a system
service for the Nix daemon.
The multi-user Nix installation creates system users and a system service for the Nix daemon.

Supported systems:

**Supported Systems**
- Linux running systemd, with SELinux disabled
- macOS

You can instruct the installer to perform a multi-user installation on
your system:
To explicitly instruct the installer to perform a multi-user installation on your system:

```console
$ curl -L https://nixos.org/nix/install | sh -s -- --daemon
```

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
can run this under your usual user account or root. The script
will invoke `sudo` as needed.
You can run this under your usual user account or `root`.
The script will invoke `sudo` as needed.

# Single User Installation

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

```console
$ curl -L https://nixos.org/nix/install | sh -s -- --no-daemon
```

In a single-user installation, `/nix` is owned by the invoking user.
The script will invoke `sudo` to create `/nix` if it doesn’t already exist.
If you don’t have `sudo`, manually create `/nix` as `root`:

```console
$ su root
# mkdir /nix
# chown alice /nix
```

# Installing from a binary tarball

You can also download a binary tarball that contains Nix and all its dependencies:
- Choose a [version](https://releases.nixos.org/?prefix=nix/) and [system type](../contributing/hacking.md#platforms)
- Download and unpack the tarball
- Run the installer

> **Note**
> **Example**
>
> If you need Nix to use a different group ID or user ID set, you will
> have to download the tarball manually and [edit the install
> script](#installing-from-a-binary-tarball).
> ```console
> $ pushd $(mktemp -d)
> $ export VERSION=2.19.2
> $ export SYSTEM=x86_64-linux
> $ curl -LO https://releases.nixos.org/nix/nix-$VERSION/nix-$VERSION-$SYSTEM.tar.xz
> $ tar xfj nix-$VERSION-$SYSTEM.tar.xz
> $ cd nix-$VERSION-$SYSTEM
> $ ./install
> $ popd
> ```
The installer will modify `/etc/bashrc`, and `/etc/zshrc` if they exist.
The installer will first back up these files with a `.backup-before-nix`
extension. The installer will also create `/etc/profile.d/nix.sh`.
The installer can be customised with the environment variables declared in the file named `install-multi-user`.
## Native packages for Linux distributions
The Nix community maintains installers for some Linux distributions in their native packaging format(https://nix-community.github.io/nix-installers/).
# macOS Installation
<!-- anchors to catch existing links -->
[]{#sect-macos-installation-change-store-prefix}[]{#sect-macos-installation-encrypted-volume}[]{#sect-macos-installation-symlink}[]{#sect-macos-installation-recommended-notes}
<!-- Note: anchors above to catch permalinks to old explanations -->
We believe we have ironed out how to cleanly support the read-only root
We believe we have ironed out how to cleanly support the read-only root file system
on modern macOS. New installs will do this automatically.
This section previously detailed the situation, options, and trade-offs,
Expand Down Expand Up @@ -126,33 +148,3 @@ this to run the installer, but it may help if you run into trouble:
boot process to avoid problems loading or restoring any programs that
need access to your Nix store
# Installing a pinned Nix version from a URL

Version-specific installation URLs for all Nix versions
since 1.11.16 can be found at [releases.nixos.org](https://releases.nixos.org/?prefix=nix/).
The corresponding SHA-256 hash can be found in the directory for the given version.

These install scripts can be used the same as usual:

```console
$ curl -L https://releases.nixos.org/nix/nix-<version>/install | sh
```

# Installing from a binary tarball

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

```console
$ cd /tmp
$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
$ cd nix-1.8-x86_64-darwin
$ ./install
```

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 `install-multi-user`.
1 change: 0 additions & 1 deletion doc/manual/src/quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ For more in-depth information you are kindly referred to subsequent chapters.
```

The install script will use `sudo`, so make sure you have sufficient rights.
On Linux, `--daemon` can be omitted for a single-user install.

For other installation methods, see the detailed [installation instructions](installation/index.md).

Expand Down

0 comments on commit 8e865f3

Please sign in to comment.