The Lix Installer

A fast, friendly, and reliable tool to help you use Lix, the community implementation of the nix tooling. Based on the Determinate Installer.

The installer works across a wide range of environments, including macOS, Linux, Windows Subsystem for Linux (WSL), SELinux, the Valve Steam Deck, and more. It can install either Lix (with flakes enabled by default), it offers support for seamlessly uninstalling Lix, it enables Lix to survive macOS upgrades, and much more.

This one liner will install Lix on any supported system:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install

Usage

Lix Installer supports the following environments, including Github Actions and GitLab:

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 (SteamOS)	✓		Stable
Windows Subsystem for Linux 2 (WSL2) (x86_64 and aarch64)	✓ (via systemd)	✓	Stable
Podman Linux containers	✓ (via systemd)	✓	Stable
Docker containers		✓	Stable

As a Github Action

You can install Lix on GitHub Actions using lix-gha-installer-action. Here's an example configuration:

on:
  pull_request:
  push:
    branches: [main]

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: samueldr/lix-gha-installer-action@8dc19fbd6451fa106a68ecb2dafeeeb90dff3a29
      - name: Run `nix build`
        run: nix build .

Planners

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

/nix/lix-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/lix-installer install linux --help

You can configure planners using environment variables or command arguments:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | NIX_BUILD_GROUP_NAME=nixbuilder sh -s -- install --nix-build-group-id 4000

# Alternatively:

NIX_BUILD_GROUP_NAME=nixbuilder ./lix-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 to see if your problem is covered.

Upgrading Lix

If you've installed Lix, you can upgrade it by running:

sudo -i nix upgrade-nix

Alternatively, you can uninstall and reinstall with a different version of Lix Installer.

Uninstalling

You can remove Lix by running:

/nix/lix-installer uninstall

On GitLab

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 Lix using this configuration:

test:
  script:
    - curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | 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 Lix:

sudo -i nix run nixpkgs#hello

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

curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install linux --init none

In a container

In Docker/Podman containers or WSL2 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 Lix's nix command:

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 (/). 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://install.lix.systems/lix | 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://install.lix.systems/lix | 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 enabling systemd, then installing Lix as normal:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install

If 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 (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 Lix's nix commands:

sudo -i nix run nixpkgs#hello

curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | 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://install.lix.systems/lix | sh -s -- install --no-confirm

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

Features

Lix installer has numerous features:

• It installs Lix with flakes enabled by default
• It enables Lix to survive macOS upgrades
• 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 Lix is present on the PATH

Quirks

While Lix 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 Lix while nix-darwin was still installed, network requests fail

Building a binary

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

As a Rust library

Lix Installer is available as a standard Rust library. See this guide for instructions on using the library in your own Rust code.

Accessing other versions

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 Lix 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

Accessing other versions

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 via --nix-package-url or NIX_INSTALLER_NIX_PACKAGE_URL= but doing so is not recommended since we haven't tested that combination. Here are some example nix package URLs including 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 CppNix installer scripts:

• In nix.conf:
  • the nix-command and flakes features are optionally enabled
  • bash-prompt-prefix is set
  • auto-optimise-store is set to true (On Linux only)
  • always-allow-substitutes is set to true
  • extra-nix-path is set to nixpkgs=flake:nixpkgs if flakes are enabled when installing
  • max-jobs is set to auto
• an installation receipt (for uninstalling) is stored at /nix/receipt.json as well as a copy of the install binary at /nix/lix-installer
• nix-channel --update is not run, ~/.nix-channels is not provisioned
• ssl-cert-file is set in /etc/nix/nix.conf if the ssl-cert-file argument is used.

Installer settings

Lix 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 (lix-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 Lix 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 Lix 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 Lix.	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 Lix 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:

lix-installer install <plan>

Alternatively, you can use the NIX_INSTALLER_PLAN environment variable:

NIX_INSTALLER_PLAN=<plan> lix-installer install

Uninstalling (lix-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):

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

Planning (lix-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 (lix-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 (lix-installer self-test)

lix-installer self-test only takes general settings.

No Telemetry Included

The Lix installer respects user privacy, and thus collects no information.