lix-installer/README.md

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.

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

Usage

Install Nix with the default planner and options:

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

Or, to download a platform specific Installer binary yourself:

$ curl -sL -o lix-installer https://install.lix.systems/lix/lix-installer-x86_64-linux
$ chmod +x lix-installer
$ ./lix-installer

lix-installer installs Lix by following a plan made by a planner. Review the available planners:

$ ./lix-installer install --help
Execute an install (possibly using an existing plan)

To pass custom options, select a planner, for example `lix-installer install linux-multi --help`

Usage: lix-installer install [OPTIONS] [PLAN]
       lix-installer install <COMMAND>

Commands:
  linux
          A planner for Linux installs
  steam-deck
          A planner suitable for the Valve Steam Deck running SteamOS
  help
          Print this message or the help of the given subcommand(s)
# ...

Planners have their own options and defaults, sharing most of them in common:

$ ./lix-installer install linux --help
A planner for Linux installs

Usage: lix-installer install linux [OPTIONS]

Options:
# ...
      --nix-build-group-name <NIX_BUILD_GROUP_NAME>
          The Nix build group name

          [env: NIX_INSTALLER_NIX_BUILD_GROUP_NAME=]
          [default: nixbld]

      --nix-build-group-id <NIX_BUILD_GROUP_ID>
          The Nix build group GID

          [env: NIX_INSTALLER_NIX_BUILD_GROUP_ID=]
          [default: 3000]
# ...

Planners can be configured via environment variable or command arguments:

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

Upgrading Lix

You can upgrade Lix with:

sudo -i nix upgrade-nix

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

Uninstalling

You can remove a lix-installer-installed Nix by running

/nix/lix-installer uninstall

Without systemd (Linux only)

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

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://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

# 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

On some container tools, such as docker, sandbox = false can be omitted. Omitting it 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][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 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.

Quirks

While lix-installer tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.

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

If any variant of nix was previously uninstalled without uninstalling nix-darwin first, users may experience errors similar to this:

$ nix shell nixpkgs#curl
error: unable to download 'https://cache.nixos.org/g8bqlgmpa4yg601w561qy2n576i6g0vh.narinfo': Problem with the SSL CA cert (path? access rights?) (77)

This occurs because nix-darwin provisions an org.nixos.activate-system service which remains after Nix is uninstalled. The org.nixos.activate-system service in this state interacts with the newly installed Nix and changes the SSL certificates it uses to be a broken symlink.

$ ls -lah /etc/ssl/certs
total 0
drwxr-xr-x  3 root  wheel    96B Oct 17 08:26 .
drwxr-xr-x  6 root  wheel   192B Sep 16 06:28 ..
lrwxr-xr-x  1 root  wheel    41B Oct 17 08:26 ca-certificates.crt -> /etc/static/ssl/certs/ca-certificates.crt

The problem is compounded by the matter that the nix-darwin uninstaller will not work after uninstalling Nix, since it uses Nix and requires network connectivity.

It's possible to resolve this situation by removing the org.nixos.activate-system service and the ca-certificates:

$ sudo rm /Library/LaunchDaemons/org.nixos.activate-system.plist
$ sudo launchctl bootout system/org.nixos.activate-system
$ /nix/lix-installer uninstall
$ sudo rm /etc/ssl/certs/ca-certificates.crt

Then run the lix-installer again, and it should work.

Up-to-date versions of the lix-installer will refuse to uninstall until nix-darwin is uninstalled first, helping mitigate this problem.

Building a binary

Since you'll be using lix-installer to install Nix on systems without Nix, the default build is a static binary.

Build a portable Linux binary on a system with Nix:

# to build a local copy
nix build -L ".#lix-installer-static"

On Mac:

# to build a local copy
nix build -L ".#lix-installer"

Then copy the result/bin/lix-installer to the machine you wish to run it on.

You can also add lix-installer to a system without Lix via cargo. There are no system dependencies to worry about:

# to build and run a local copy
RUSTFLAGS="--cfg tokio_unstable" cargo run -- --help
# to build the remote main development branch
RUSTFLAGS="--cfg tokio_unstable" cargo install --git https://git.lix.systems/lix-project/lix-installer
lix-installer --help
# for a specific version of the installer:
export NIX_INSTALLER_TAG="v0.6.0"
RUSTFLAGS="--cfg tokio_unstable" cargo install --git https://git.lix.systems/lix-project/lix-installer --tag $NIX_INSTALLER_TAG
lix-installer --help

To make this build portable, pass --target x86_64-unknown-linux-musl.

Note

We currently require --cfg tokio_unstable as we utilize Tokio's process groups, which wrap stable std APIs, but are unstable due to it requiring an MSRV bump.

As a library

Warning

Use as a library is still experimental. This feature is likely to be removed in the future without an advocate. If you're using this, please let us know and we can make a path to stabilization.

Add lix-installer to your dependencies:

cargo add lix-installer

If you are building a CLI, check out the cli feature flag for clap integration.

You'll also need to edit your .cargo/config.toml to use tokio_unstable as we utilize Tokio's process groups, which wrap stable std APIs, but are unstable due to it requiring an MSRV bump:

# .cargo/config.toml
[build]
rustflags=["--cfg", "tokio_unstable"]

Then it's possible to review the documentation:

cargo doc --open -p lix-installer

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)
  • 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.

No Telemetry Included

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