NixOS/experimental-nix-installer

An experimental fork of the Determinate Nix Installer to explore upstreaming.

Source code at GitHub https://github.com/NixOS/experimental-nix-installer

{
  "createdAt": "2023-05-10T14:49:04Z",
  "defaultBranch": "main",
  "description": "An experimental fork of the Determinate Nix Installer to explore upstreaming.",
  "fullName": "NixOS/experimental-nix-installer",
  "homepage": "",
  "language": "Rust",
  "name": "experimental-nix-installer",
  "pushedAt": "2025-11-26T15:08:07Z",
  "stargazersCount": 111,
  "topics": [],
  "updatedAt": "2025-11-26T15:08:12Z",
  "url": "https://github.com/NixOS/experimental-nix-installer"
}

An experimental fork of the Determinate Nix Installer, to play with upstreaming.

Note, this is different from the Determinate Nix Installer, available at https://github.com/DeterminateSystems/nix-installer.

If you’re having a problem with installing Nix, this repository is almost certainly the wrong place to record issues.

If you used the official Nix install scripts, report issues at https://github.com/NixOS/nix/issues.

If you used the Determinate Nix Installer, report issues at https://github.com/DeterminateSystems/nix-installer.

This one-liner is the quickest way to get started on any supported system:

curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
  sh -s -- install

Platform	Multi user?	`root` only	Maturity
Linux (`x86_64` and `aarch64`)	✓ (via [systemd])	✓	Stable
MacOS (`x86_64` and `aarch64`)	✓		Stable (see note)
[Valve Steam Deck][steam-deck] (SteamOS)	✓		Stable
[Windows Subsystem for Linux][wsl] 2 (WSL2) (`x86_64` and `aarch64`)	✓ (via [systemd])	✓	Stable
[Podman] Linux containers	✓ (via [systemd])	✓	Stable
[Docker] containers		✓	Stable

Install Nix

You can install Nix with the default planner and options by running this script:

curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
  sh -s -- install

To download a platform-specific installer binary yourself:

curl -sL -o nix-installer https://artifacts.nixos.org/experimental-installer/nix-installer-x86_64-linux
chmod +x nix-installer
./nix-installer

This would install Nix on an x86_64-linux system but you can replace that with the system of your choice.

Planners

Determinate Nix Installer installs Nix by following a plan made by a planner. To review the available planners:

/nix/nix-installer install --help

Planners have their own options and defaults, sharing most of them in common. To see the options for Linux, for example:

/nix/nix-installer install linux --help

You can configure planners using environment variables or command arguments:

curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
  NIX_BUILD_GROUP_NAME=nixbuilder sh -s -- install --nix-build-group-id 4000

# Alternatively:

NIX_BUILD_GROUP_NAME=nixbuilder ./nix-installer install --nix-build-group-id 4000

See Installer settings below for a full list of options.

Troubleshooting

Having problems with the installer? Consult our [troubleshooting guide]!(./docs/troubleshooting.md) to see if your problem is covered.

Upgrading Nix

You can upgrade Nix by running:

sudo -i nix upgrade-nix

Alternatively, you can uninstall and reinstall with a different version of the installer.

Uninstalling

You can remove Nix installed by Determinate Nix Installer by running:

/nix/nix-installer uninstall

On GitLab

[GitLab CI][gitlab-ci] runners are typically [Docker] based and run as the root user. This means that systemd is not present, so you need to pass the --init none option to the Linux planner.

On the default [GitLab] runners, you can install Nix using this configuration:

test:
  script:
    - curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | sh -s -- install linux --no-confirm --init none
    - . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
    - nix run nixpkgs#hello
    - nix profile install nixpkgs#hello
    - hello

If you are using different runners, the above example may need to be adjusted.

Without systemd (Linux only)

[!WARNING] When --init none is used, only root or users who can elevate to root privileges can run Nix:
Terminal window
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 --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-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:
Terminal window
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 --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | sh -s -- install linux \
  --extra-conf "sandbox = false" \
  --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 --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | sh -s -- install linux \
  --extra-conf "sandbox = false" \
  --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 WSL2

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

curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-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:
Terminal window
sudo -i nix run nixpkgs#hello

curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-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 --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-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 experimental 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 experimental 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]!(./docs/quirks.md) for information on resolving these issues:

[Using MacOS after removing Nix while nix-darwin was still installed, network requests fail]!(./docs/quirks.md#using-macos-after-removing-nix-while-nix-darwin-was-still-installed-network-requests-fail)

Building a binary

See [this guide]!(./docs/building.md) for instructions on building and distributing the installer yourself.

As a Rust library

The Determinate Nix Installer is available as a standard [Rust] library. See [this guide]!(./docs/rust-library.md) for instructions on using the library in your own Rust code.

Accessing other versions

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

VERSION="v0.6.0"
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-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/experimental-nix-installer/releases/download/${VERSION}/nix-installer-${ARCH} -o nix-installer
./nix-installer install

Each installer version has an [associated supported nix version]!(src/settings.rs)—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:

Installation differences

Differing from the upstream [Nix][upstream-nix] installer scripts:

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

Determinate 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
`--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)	`_nixbld` (macOS), `nixbld` (Linux)	`NIX_INSTALLER_NIX_BUILD_USER_PREFIX`
`--nix-package-url`	The Nix package URL		`NIX_INSTALLER_NIX_PACKAGE_URL`
`--no-confirm`	Run installation without requiring explicit user confirmation	`false`	`NIX_INSTALLER_NO_CONFIRM`
`--no-modify-profile`	Modify the user profile to automatically load Nix.	`true`	`NIX_INSTALLER_MODIFY_PROFILE`
`--proxy`	The proxy to use (if any); valid proxy bases are `https://$URL`, `http://$URL` and `socks5://$URL`		`NIX_INSTALLER_PROXY`
`--ssl-cert-file`	An SSL cert to use (if any); used for fetching Nix and sets `ssl-cert-file` in `/etc/nix/nix.conf`		`NIX_INSTALLER_SSL_CERT_FILE`
`--no-start-daemon`	Start the daemon (if not `--init none`)	`true`	`NIX_INSTALLER_START_DAEMON`

You can also specify a planner with the first argument:

nix-installer install <plan>

Alternatively, you can use the NIX_INSTALLER_PLAN environment variable:

NIX_INSTALLER_PLAN=<plan> nix-installer install

Uninstalling (`nix-installer uninstall`)

Flag(s)	Description	Default (if any)	Environment variable
`--explain`	Provide an explanation of the changes the installation process will make to your system	`false`	`NIX_INSTALLER_EXPLAIN`
`--no-confirm`	Run installation without requiring explicit user confirmation	`false`	`NIX_INSTALLER_NO_CONFIRM`

You can also specify an installation receipt as the first argument (the default is /nix/receipt.json):

nix-installer uninstall /path/to/receipt.json

Planning (`nix-installer plan`)

Flag(s)	Description	Default (if any)	Environment variable
`--out-file`	Where to write the generated plan (in JSON format)	`/dev/stdout`	`NIX_INSTALLER_PLAN_OUT_FILE`

Repairing (`nix-installer repair`)

Flag(s)	Description	Default (if any)	Environment variable
`--no-confirm`	Run installation without requiring explicit user confirmation	`false`	`NIX_INSTALLER_NO_CONFIRM`

Self-test (`nix-installer self-test`)

nix-installer self-test only takes general settings.

NixOS/experimental-nix-installer

An experimental fork of the Determinate Nix Installer, to play with upstreaming.

If you’re having a problem with installing Nix, this repository is almost certainly the wrong place to record issues.

Install Nix

Planners

Troubleshooting

Upgrading Nix

Uninstalling

On GitLab

Without systemd (Linux only)

In a container

In WSL2

Skip confirmation

Features

Nix community involvement

Quirks

Building a binary

As a Rust library

Accessing other versions

Installation differences

Installer settings

General settings

Installation (nix-installer install)

Uninstalling (nix-installer uninstall)

Planning (nix-installer plan)

Repairing (nix-installer repair)

Self-test (nix-installer self-test)

Installation (`nix-installer install`)

Uninstalling (`nix-installer uninstall`)

Planning (`nix-installer plan`)

Repairing (`nix-installer repair`)

Self-test (`nix-installer self-test`)