diff --git a/README.md b/README.md
index 0ae9e5b..2053c91 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,16 @@
-# Install Nix with flakes using the Determinate Nix Installer
-
-_🎉 Celebrating over 500,000 successful installations! 🎉_
+# The Determinate Nix Installer
[](https://crates.io/crates/nix-installer)
[](https://docs.rs/nix-installer/latest/nix_installer/)
-`nix-installer`, the fast and reliable Nix installer.
+A fast, friendly, and reliable tool to help you use Nix with Flakes everywhere.
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
-The `nix-installer` tool is ready to use in a number of environments:
+The `nix-installer` has successfully completed over 500,000 installs in a number of environments, including [Github Actions](#as-a-github-action):
| Platform | Multi User | `root` only | Maturity |
|------------------------------|:------------------:|:-----------:|:-----------------:|
@@ -27,32 +25,6 @@ The `nix-installer` tool is ready to use in a number of environments:
> **Note**
> On **MacOS only**, removing users and/or groups may fail if there are no users who are logged in graphically.
-## Installation Differences
-
-Differing from the upstream [Nix](https://github.com/NixOS/nix) installer scripts:
-
-* In `nix.conf`:
- + the `auto-allocate-uids`, `nix-command` and `flakes` features are 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`
- * `auto-allocate-uids` is set to `true`. (On Linux only)
-* an installation receipt (for uninstalling) is stored at `/nix/receipt.json` as well as a copy of the install binary at `/nix/nix-installer`
-* `nix-channel --update` is not run, `~/.nix-channels` is not provisioned
-* `NIX_SSL_CERT_FILE` is set in the various shell profiles if the `ssl-cert-file` argument is used.
-
-## Motivations
-
-The upstream scripts do a good job, however they are difficult to maintain.
-Subtle differences in the shell implementations and certain characteristics of Bash scripts make it difficult to make meaningful changes to the installer.
-
-The Determinate Nix installer has numerous advantages:
-
-* keeping an installation receipt for easy uninstallation
-* offering users a chance to review an accurate, calculated install plan
-* having 'planners' which can create appropriate install plans for complicated targets
-* offering users with a failing install the chance to do a best-effort revert
-* improving performance by maximizing parallel operations
## Usage
@@ -67,12 +39,9 @@ Or, to download a platform specific Installer binary yourself:
```bash
$ curl -sL -o nix-installer https://install.determinate.systems/nix/nix-installer-x86_64-linux
$ chmod +x nix-installer
+$ ./nix-installer
```
-> **Note**
-> `nix-installer` will elevate itself if needed using `sudo`.
-> If you use `doas` or `please` you may need to elevate `nix-installer` yourself.
-
`nix-installer` installs Nix by following a *plan* made by a *planner*. Review the available planners:
```bash
@@ -127,7 +96,7 @@ $ NIX_BUILD_GROUP_NAME=nixbuilder ./nix-installer install linux-multi --nix-buil
```
-## Uninstalling
+### Uninstalling
You can remove a `nix-installer`-installed Nix by running
@@ -136,7 +105,7 @@ You can remove a `nix-installer`-installed Nix by running
```
-## As a Github Action
+### As a Github Action
You can use the [`nix-installer-action`](https://github.com/DeterminateSystems/nix-installer-action) Github Action like so:
@@ -158,7 +127,7 @@ jobs:
run: nix build .
```
-## Without systemd (Linux only)
+### Without systemd (Linux only)
> **Warning**
> When `--init none` is used, _only_ `root` or users who can elevate to `root` privileges can run Nix:
@@ -173,7 +142,7 @@ If you don't use [systemd], you can still install Nix by explicitly specifying t
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install linux --init none
```
-## In a container
+### In a container
In Docker/Podman containers or WSL2 instances where an init (like `systemd`) is not present, pass `--init none`.
@@ -236,15 +205,29 @@ 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
+### In WSL2
+
+We **strongly recommend** [enabling systemd](https://ubuntu.com/blog/ubuntu-wsl-enable-systemd), then installing Nix as normal:
-If [systemd is enabled](https://ubuntu.com/blog/ubuntu-wsl-enable-systemd) it's possible to install Nix as normal using the command at the top of this document:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
-If systemd is not enabled, pass `--init none` at the end of the command:
+If [WSLg][wslg] is enabled, you can do things like open a Linux Firefox from Windows on Powershell:
+
+```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):
+
+```powershell
+wsl nix run --impure github:guibou/nixGL nix run nixpkgs#obs-studio
+```
+
+
+If enabling system 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:
@@ -258,7 +241,7 @@ If systemd is not enabled, pass `--init none` at the end of the command:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install linux --init none
```
-## Skip confirmation
+### Skip confirmation
If you'd like to bypass the confirmation step, you can apply the `--no-confirm` flag:
@@ -268,6 +251,54 @@ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix
This is especially useful when using the installer in non-interactive scripts.
+
+## Quirks
+
+While `nix-installer` tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.
+
+### Using MacOS remote SSH builders, Nix binaries are not on `$PATH`
+
+When connecting to a Mac remote SSH builder users may sometimes see this error:
+
+```bash
+$ nix store ping --store "ssh://$USER@$HOST"
+Store URL: ssh://$USER@$HOST
+zsh:1: command not found: nix-store
+error: cannot connect to '$USER@$HOST'
+```
+
+The way MacOS populates the `PATH` environment differs from other environments. ([Some background](https://gist.github.com/Linerre/f11ad4a6a934dcf01ee8415c9457e7b2))
+
+There are two possible workarounds for this:
+
+* **(Preferred)** Update the remote builder URL to include the `remote-program` parameter pointing to `nix-store`. For example:
+ ```bash
+ nix store ping --store "ssh://$USER@$HOST?remote-program=/nix/var/nix/profiles/default/bin/nix-store"
+ ```
+ If you are unsure where the `nix-store` binary is located, run `which nix-store` on the remote.
+* Update `/etc/zshenv` on the remote so that `zsh` populates the Nix path for every shell, even those that are neither *interactive* or *login*:
+ ```bash
+ # Nix
+ if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
+ . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
+ fi
+ # End Nix
+ ```
+
+ This strategy has some behavioral caveats, namely, $PATH may have unexpected contents
+
+ For example, if `$PATH` gets unset then a script invoked, `$PATH` may not be as empty as expected:
+ ```bash
+ $ cat example.sh
+ #! /bin/zsh
+ echo $PATH
+ $ PATH= ./example.sh
+ /Users/ephemeraladmin/.nix-profile/bin:/nix/var/nix/profiles/default/bin:
+ ```
+ This strategy results in Nix's paths being present on `$PATH` twice and may have a minor impact on performance.
+
+
+
## Building a binary
Since you'll be using `nix-installer` to install Nix on systems without Nix, the default build is a static binary.
@@ -298,7 +329,7 @@ nix build -L "github:determinatesystems/nix-installer/$NIX_INSTALLER_TAG#nix-ins
Then copy the `result/bin/nix-installer` to the machine you wish to run it on.
-You can also add `nix-installer` to a system without Nix via `cargo`:
+You can also add `nix-installer` to a system without Nix via `cargo`, there are no system dependencies to worry about:
```bash
# to build and run a local copy
@@ -321,7 +352,7 @@ To make this build portable, pass ` --target x86_64-unknown-linux-musl`.
## As a library
> **Warning**
-> Use as a library is still experimental, if you're using this, please let us know and we can make a path to stablization.
+> 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 stablization.
Add `nix-installer` to your dependencies:
@@ -372,52 +403,40 @@ curl -sSf -L https://github.com/DeterminateSystems/nix-installer/releases/downlo
./nix-installer install
```
-## Quirks
-While `nix-installer` tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.
+## Installation Differences
-### Using MacOS remote SSH builders, Nix binaries are not on `$PATH`
+Differing from the upstream [Nix](https://github.com/NixOS/nix) installer scripts:
-When connecting to a Mac remote SSH builder users may sometimes see this error:
+* In `nix.conf`:
+ + the `auto-allocate-uids`, `nix-command` and `flakes` features are 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`
+ * `auto-allocate-uids` is set to `true`. (On Linux only)
+* an installation receipt (for uninstalling) is stored at `/nix/receipt.json` as well as a copy of the install binary at `/nix/nix-installer`
+* `nix-channel --update` is not run, `~/.nix-channels` is not provisioned
+* `NIX_SSL_CERT_FILE` is set in the various shell profiles if the `ssl-cert-file` argument is used.
-```bash
-$ nix store ping --store "ssh://$USER@$HOST"
-Store URL: ssh://$USER@$HOST
-zsh:1: command not found: nix-store
-error: cannot connect to '$USER@$HOST'
-```
+## Motivations
-The way MacOS populates the `PATH` environment differs from other environments. ([Some background](https://gist.github.com/Linerre/f11ad4a6a934dcf01ee8415c9457e7b2))
+The existing upstream scripts do a good job, however they are difficult to maintain.
-There are two possible workarounds for this:
+Subtle differences in the shell implementations and tool used in the scripts make it difficult to make meaningful changes to the installer.
-* **(Preferred)** Update the remote builder URL to include the `remote-program` parameter pointing to `nix-store`. For example:
- ```bash
- nix store ping --store "ssh://$USER@$HOST?remote-program=/nix/var/nix/profiles/default/bin/nix-store"
- ```
- If you are unsure where the `nix-store` binary is located, run `which nix-store` on the remote.
-* Update `/etc/zshenv` on the remote so that `zsh` populates the Nix path for every shell, even those that are neither *interactive* or *login*:
- ```bash
- # Nix
- if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
- . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
- fi
- # End Nix
- ```
-
- This strategy has some behavioral caveats, namely, $PATH may have unexpected contents
+The Determinate Nix installer has numerous advantages:
- For example, if `$PATH` gets unset then a script invoked, `$PATH` may not be as empty as expected:
- ```bash
- $ cat example.sh
- #! /bin/zsh
- echo $PATH
- $ PATH= ./example.sh
- /Users/ephemeraladmin/.nix-profile/bin:/nix/var/nix/profiles/default/bin:
- ```
- This strategy results in Nix's paths being present on `$PATH` twice and may have a minor impact on performance.
+* keeping an installation receipt for easy uninstallation
+* offering users a chance to review an accurate, calculated install plan
+* having 'planners' which can create appropriate install plans for complicated targets
+* offering users with a failing install the chance to do a best-effort revert
+* improving performance by maximizing parallel operations
+* supporting a expanded test suite including 'curing' cases
+* supporting SELinux and OSTree based distributions without asking users to make compromises
+* operating as a single, static binary with external dependencies such as `openssl`, only calling existing system tools (like `useradd`) where necessary
+
+It has been wonderful to collaborate with other participants in the Nix Installer Working Group and members of the broader community. The working group maintains a [foundation owned fork of the installer](https://github.com/nixos/experimental-nix-installer/).
-
## Diagnostics
@@ -447,3 +466,5 @@ You can read the full privacy policy for [Determinate Systems][detsys], the crea
[diagnosticdata]: https://github.com/DeterminateSystems/nix-installer/blob/f9f927840d532b71f41670382a30cfcbea2d8a35/src/diagnostics.rs#L29-L43
[privacy]: https://determinate.systems/privacy
[systemd]: https://systemd.io
+[wslg]: https://github.com/microsoft/wslg
+[nixgl]: https://github.com/guibou/nixGL
\ No newline at end of file