nix-installer

Nix Installer

Status: Beta

This is the official Nix installer maintained by the NixOS community. It is different from the Determinate Nix Installer and the nixos.org/nix/install shell script bundled with Nix.

If you're having a problem with installing Nix, make sure to report issues in the right place.

If you used `sh [!WARNING]

When --init none is used, only root or users who can elevate to root privileges can run Nix:

sudo -i nix run nixpkgs#hello

If you don't use [systemd], you can still install Nix by explicitly specifying the linux plan and --init none:

curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install linux --init none

In a container

In [Docker]/[Podman] containers or [WSL2][wsl] instances where an init (like systemd) is not present, pass --init none.

For containers (without an init):

[!WARNING] When --init none is used, only root or users who can elevate to root privileges can run Nix:

sudo -i nix run nixpkgs#hello

[!WARNING] If you want to add a flake.nix, first declare a working directory (such as /src) in your Dockerfile. You cannot lock a flake placed at the docker image root (/) (see details). You would get a file '/dev/full' has an unsupported type during the docker build.

# append this to the below dockerfiles
WORKDIR /src
# now flakes will work
RUN nix flake init
RUN nix flake lock

# Dockerfile
FROM ubuntu:latest
RUN apt update -y
RUN apt install curl -y
RUN curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install linux \
  --extra-conf "sandbox = false" --enable-flakes --init none --no-confirm
ENV PATH="${PATH}:/nix/var/nix/profiles/default/bin"
RUN nix run nixpkgs#hello

docker build -t ubuntu-with-nix .
docker run --rm -ti ubuntu-with-nix
docker rmi ubuntu-with-nix
# or
podman build -t ubuntu-with-nix .
podman run --rm -ti ubuntu-with-nix
podman rmi ubuntu-with-nix

For containers with a [systemd] init:

# Dockerfile
FROM ubuntu:latest
RUN apt update -y
RUN apt install curl systemd -y
RUN curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install linux \
  --extra-conf "sandbox = false" --enable-flakes --no-start-daemon --no-confirm
ENV PATH="${PATH}:/nix/var/nix/profiles/default/bin"
RUN nix run nixpkgs#hello
CMD [ "/bin/systemd" ]

podman build -t ubuntu-systemd-with-nix .
IMAGE=$(podman create ubuntu-systemd-with-nix)
CONTAINER=$(podman start $IMAGE)
podman exec -ti $CONTAINER /bin/bash
podman rm -f $CONTAINER
podman rmi $IMAGE

With some container tools, such as [Docker], you can omit sandbox = false. Omitting this will negatively impact compatibility with container tools like [Podman].

In GitHub Actions

The nix installer action repository provides a GitHub Action for installing Nix in CI workflows. It uses this installer under the hood.

Basic usage:

- uses: NixOS/nix-installer-action@main

Install specific version:

- uses: NixOS/nix-installer-action@main
  with:
    installer-version: 2.33.3

No-init mode (for containers):

- uses: NixOS/nix-installer-action@main
  with:
    init: "no"

See the action inputs for all available options.

In WSL2

We strongly recommend first [enabling systemd][enabling-systemd] and then installing Nix as normal:

curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install

If [WSLg][wslg] is enabled, you can do things like open a Linux Firefox from Windows on Powershell:

wsl nix run nixpkgs#firefox

To use some OpenGL applications, you can use [nixGL][nixgl] (note that some applications, such as blender, may not work):

wsl nix run --impure github:guibou/nixGL nix run nixpkgs#obs-studio

If enabling systemd is not an option, pass --init none at the end of the command:

[!WARNING] When --init none is used, only root or users who can elevate to root privileges can run Nix:

sudo -i nix run nixpkgs#hello

curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install linux --init none

Skip confirmation

If you'd like to bypass the confirmation step, you can apply the --no-confirm flag:

curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install --no-confirm

This is especially useful when using the installer in non-interactive scripts.

Features

Existing Nix installation scripts do a good job but they are difficult to maintain.

Subtle differences in the shell implementations and tool used in the scripts make it difficult to make meaningful changes to the installer.

The Nix installer has numerous advantages over these options:

• It keeps an installation receipt for easy uninstallation
• It uses planners to create appropriate install plans for complicated targets—plans that you can review prior to installation
• It enables you to perform a best-effort reversion in the facing of a failed install
• It improves installation performance by maximizing parallel operations
• It supports an expanded test suite including "curing" cases (compatibility with Nix already on the system)
• It supports SELinux and OSTree-based distributions without asking users to make compromises
• It operates as a single, static binary with external dependencies such as [OpenSSL], only calling existing system tools (like useradd) when necessary
• As a macOS remote build target, it ensures that Nix is present on the PATH

Nix community involvement

It has been wonderful to collaborate with other participants in the [Nix Installer Working Group][wg] and members of the broader community. The working group maintains a [foundation-owned fork of the installer][forked-installer].

Quirks

While the Nix Installer tries to provide a comprehensive and unquirky experience, there are unfortunately some issues that may require manual intervention or operator choices. See this document for information on resolving these issues:

• Using MacOS after removing Nix while nix-darwin was still installed, network requests fail

Building a binary

See this guide for instructions on building and distributing the installer yourself.

Accessing other versions

You can pin to a specific version of the Nix installer by modifying the download URL. Here's an example:

VERSION="v0.6.0"
curl -sSfL https://artifacts.nixos.org/nix-installer/tag/${VERSION}/nix-installer.sh | sh -s -- install

To discover which versions are available, or download the binaries for any release, check the [Github Releases][releases].

You can download and use these releases directly. Here's an example:

VERSION="v0.6.0"
ARCH="aarch64-linux"
curl -sSf -L https://github.com/NixOS/nix-installer/releases/download/${VERSION}/nix-installer-${ARCH} -o nix-installer
./nix-installer install

Each installer version has an associated supported nix version—if you pin the installer version, you'll also indirectly pin to the associated nix version.

You can also override the Nix version using --nix-package-url or NIX_INSTALLER_NIX_PACKAGE_URL= but doing this is not recommended since we haven't tested that combination. Here are some example Nix package URLs, including the Nix version, OS, and architecture:

• https://releases.nixos.org/nix/nix-2.18.1/nix-2.18.1-x86_64-linux.tar.xz
• https://releases.nixos.org/nix/nix-2.18.1/nix-2.18.1-aarch64-darwin.tar.xz

Installation differences

Differing from the [nixos.org/nix/install][upstream-nix] script:

• an installation receipt (for uninstalling) is stored at /nix/receipt.json as well as a copy of the install binary at /nix/nix-installer
• ssl-cert-file is set in /etc/nix/nix.conf if the ssl-cert-file argument is used.

Installer settings

The Nix installer provides a variety of configuration settings, some general and some on a per-command basis. All settings are available via flags or via NIX_INSTALLER_* environment variables.

General settings

These settings are available for all commands.

Flag(s)	Description	Default (if any)	Environment variable
--log-directives	Tracing directives delimited by comma		NIX_INSTALLER_LOG_DIRECTIVES
--logger	Which logger to use (options are compact, full, pretty, and json)	compact	NIX_INSTALLER_LOGGER
--verbose	Enable debug logs, (-vv for trace)	false	NIX_INSTALLER_VERBOSITY

Installation (nix-installer install)

Flag(s)	Description	Default (if any)	Environment variable
--enable-flakes	Enable the flakes experimental feature	false	NIX_INSTALLER_ENABLE_FLAKES
--explain	Provide an explanation of the changes the installation process will make to your system	false	NIX_INSTALLER_EXPLAIN
--extra-conf	Extra configuration lines for /etc/nix.conf		NIX_INSTALLER_EXTRA_CONF
--force	Whether the installer should forcibly recreate files it finds existing	false	NIX_INSTALLER_FORCE
--init	Which init system to configure (if --init none Nix will be root-only)	launchd (macOS), systemd (Linux)	NIX_INSTALLER_INIT
--nix-build-group-id	The Nix build group GID	350 (macOS), 30000 (Linux)	NIX_INSTALLER_NIX_BUILD_GROUP_ID
--nix-build-group-name	The Nix build group name	nixbld	NIX_INSTALLER_NIX_BUILD_GROUP_NAME
--nix-build-user-count	The number of build users to create	32	NIX_INSTALLER_NIX_BUILD_USER_COUNT
--nix-build-user-id-base	The Nix build user base UID (ascending) (NOTE: the first UID will be this base + 1)	350 (macOS), 30000 (Linux)	NIX_INSTALLER_NIX_BUILD_USER_ID_BASE
--nix-build-user-prefix	The Nix build user prefix (user numbers will be postfixed)	`_nixbl