From fcc8d27ef43258ecb84177f14c138c86397e10ba Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Mon, 3 Aug 2026 09:50:16 -0700 Subject: [PATCH 1/4] Add the get.flox.dev install script to the install options Documents the curl|sh installer as a new "Install Script" tab on the install page, with verified sample transcripts, the existing-Nix behavior (nix profile install + Flox cache in nix.conf), sudo command preview, refused systems, and FLOX_CHANNEL/FLOX_VERSION pinning. Adds matching uninstall/troubleshooting tabs and mentions on the index and repo-install tutorial. Co-Authored-By: Claude Fable 5 --- index.mdx | 2 +- install-flox/install.mdx | 120 +++++++++++++++++++++++++++++ install-flox/troubleshooting.mdx | 19 ++++- install-flox/uninstall.mdx | 23 ++++++ tutorials/installing-from-repo.mdx | 4 +- 5 files changed, 165 insertions(+), 3 deletions(-) diff --git a/index.mdx b/index.mdx index 216de9b..3e90b2e 100644 --- a/index.mdx +++ b/index.mdx @@ -22,7 +22,7 @@ Flox makes it easy to work locally, test in CI, and deploy to production—all w - Install `flox` with `apt`, `yum`, `brew`, or a standalone installer to get your dev environment set up in minutes. + Install `flox` with one command (`curl -fsSL https://get.flox.dev | sh`), or with `apt`, `yum`, `brew`, or a standalone installer to get your dev environment set up in minutes. [Download & Install](/install-flox/install) diff --git a/install-flox/install.mdx b/install-flox/install.mdx index 18333b4..d2eaec6 100644 --- a/install-flox/install.mdx +++ b/install-flox/install.mdx @@ -12,6 +12,126 @@ description: "How to install or upgrade the Flox CLI" Flox 1.14.0 online. + + + **Install with one command** + + The install script detects your OS and CPU architecture and installs Flox + with the best method available on your machine. It supports MacOS and + Debian- and Red Hat-based Linux distributions, on `x86_64` and `aarch64`. + + ```bash + curl -fsSL https://get.flox.dev | sh + ``` + + The script picks an install method in this order: + + 1. If Nix is already installed, the script installs Flox through your + existing Nix with `nix profile install` — it does not replace your + Nix, it only adds the Flox cache to `nix.conf`. + 1. On MacOS, it downloads and runs the `.pkg` installer. + 1. On Debian- and Ubuntu-family systems, it installs the `.deb` package + with `apt`. + 1. On Fedora- and RHEL-family systems, it installs the `.rpm` package + with `dnf` or `yum`. + + If Flox is already installed, the script makes no changes and instead + prints the upgrade command for your package manager. + + + **Privileged commands are shown before they run** + + Before using `sudo`, the script prints the exact commands it is about + to run with elevated privileges, so you know what you are agreeing to. + You may be prompted for your `sudo` password. + + + Here is what an install looks like on Ubuntu: + + ```console + $ curl -fsSL https://get.flox.dev | sh + ==> Resolving the latest Flox version (stable channel)... + ==> Installing Flox 1.14.0 for x86_64-linux + ==> Downloading https://downloads.flox.dev/by-env/stable/deb/flox-1.14.0.x86_64-linux.deb + ==> The following commands will be run with sudo: + sudo apt-get install -y /tmp/flox-install.XXXXXX/flox-1.14.0.x86_64-linux.deb + ==> Installing the .deb package with apt + ... + ``` + + + + The script does **not** replace or reconfigure an existing Nix + installation. Instead it installs Flox into your Nix profile: + + 1. Adds the Flox cache (`https://cache.flox.dev`) and its public + signing key to `nix.conf` — system-wide when `sudo` is available, + otherwise user-level — and restarts `nix-daemon` if one is running. + 1. Installs Flox with `nix profile install github:flox/flox/latest`. + + ```console + $ curl -fsSL https://get.flox.dev | sh + ==> Adding the Flox cache (https://cache.flox.dev) to /etc/nix/nix.conf + ==> The following commands will be run with sudo: + sudo mkdir -p /etc/nix + sudo tee -a /etc/nix/nix.conf + ==> The following commands will be run with sudo: + sudo systemctl restart nix-daemon + ==> Nix detected — installing Flox via nix profile install (github:flox/flox/latest) + ... + ``` + + If you would rather configure Nix yourself, see the + [Nix (Generic)](#nix-generic) instructions. + + + **Unsupported systems** + + The script refuses to run on systems where the native packages are + untested: immutable (ostree-based) distributions such as Fedora + Silverblue or CoreOS, openSUSE/SLES, and RPM-family systems without + `dnf` or `yum`. On those systems, install Nix first and then follow the + [Nix (Generic)](#nix-generic) instructions. + + + **Pin a channel or version** + + The script honors two environment variables: + + ```console + $ curl -fsSL https://get.flox.dev | FLOX_CHANNEL= sh + $ curl -fsSL https://get.flox.dev | FLOX_VERSION= sh + ``` + + `FLOX_CHANNEL` (default `stable`) selects the release channel. + `FLOX_VERSION` pins an exact version instead of the channel's latest. + When Flox is installed through an existing Nix, `FLOX_CHANNEL` is + ignored: the script installs `github:flox/flox/latest`, or + `github:flox/flox/v` when `FLOX_VERSION` is set. + + **Verify Flox installation** + + If the following command returns without error then you're ready to get + started! + + ```console + $ flox --version + 1.14.0 + + ``` + + The version you see might be different. + + **Upgrade existing Flox installation** + + The script does not upgrade an existing installation. Re-running it on a + system that already has Flox prints the upgrade command for your package + manager, for example: + + ```bash + sudo apt-get update && sudo apt-get install --only-upgrade flox + ``` + Install Flox with the standalone [`.pkg` installer](#pkg-installer) or diff --git a/install-flox/troubleshooting.mdx b/install-flox/troubleshooting.mdx index 3cf3f9c..df9d000 100644 --- a/install-flox/troubleshooting.mdx +++ b/install-flox/troubleshooting.mdx @@ -77,6 +77,23 @@ If you have a partial Flox installation, you can run Flox uninstallation. + + + The install script installs Flox with your system package manager, or + through Nix if Nix was already present. Follow the tab that matches how + the script installed Flox: [MacOS (Pkg)](#macos-pkg) on MacOS, + [Debian](#debian) on Debian- and Ubuntu-family systems, or + [RPM](#rpm) on Fedora- and RHEL-family systems. If Flox was installed + through an existing Nix, remove it with: + + ```bash + nix profile remove flox + ``` + + If that reports no matching entry, run `nix profile list` to find the + right name (on older Nix, remove by index or with + `nix profile remove github:flox/flox/latest`). + @@ -398,7 +415,7 @@ filling out the `Install failure` Issue template. Please include: - Your operating system and version -- The installation method you used (Pkg, Homebrew, Debian, RPM, etc.) +- The installation method you used (install script, Pkg, Homebrew, Debian, RPM, etc.) - The full install log output (see [Finding install logs](#finding-install-logs) above) - Any error messages you encountered diff --git a/install-flox/uninstall.mdx b/install-flox/uninstall.mdx index 21470c3..44b368f 100644 --- a/install-flox/uninstall.mdx +++ b/install-flox/uninstall.mdx @@ -15,6 +15,29 @@ Here's how to **completely remove `flox` from your system**. + + + The install script installs Flox with your system package manager, or + through Nix if Nix was already present. Uninstall with the method that + matches how the script installed Flox: + + * On MacOS, follow the [MacOS (Pkg)](#macos-pkg) tab. + * On Debian- and Ubuntu-family systems, follow the [Debian](#debian) tab. + * On Fedora- and RHEL-family systems, follow the [RPM](#rpm) tab. + * If Flox was installed through an existing Nix, remove it from your Nix + profile: + + ```bash + nix profile remove flox + ``` + + If that reports no matching entry, run `nix profile list` to find the + right name (on older Nix, remove by index or with + `nix profile remove github:flox/flox/latest`). + To also remove the cache configuration the script added, + delete the lines under `# Added by the Flox installer (get.flox.dev)` + in `/etc/nix/nix.conf` (or `~/.config/nix/nix.conf`). + diff --git a/tutorials/installing-from-repo.mdx b/tutorials/installing-from-repo.mdx index 0776fe1..334de26 100644 --- a/tutorials/installing-from-repo.mdx +++ b/tutorials/installing-from-repo.mdx @@ -14,7 +14,9 @@ as they are released. When you [download and install a Flox `.deb` or `.rpm` package](/install-flox/install), - the installer performs these steps for you. + the installer performs these steps for you, and the + [install script](/install-flox/install) (`curl -fsSL https://get.flox.dev | sh`) + automates the download as well. But you can easily script the steps below to automate this process. These instructions cover the process of installing from Flox's repository From 76ea0ead5c5d7010cbdd8e42255ab170cdf86965 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Wed, 5 Aug 2026 09:20:37 -0700 Subject: [PATCH 2/4] docs(install): script no longer installs through Nix Per spec review, the install script now stops when it detects an existing Nix and links to the consolidated Nix tab instead of running nix profile install. Drop the nix-path accordion and the nix profile remove instructions from the install/uninstall/troubleshooting tabs, and point remaining links at the consolidated #nix anchor. Co-Authored-By: Claude Fable 5 --- install-flox/install.mdx | 47 ++++++++------------------------ install-flox/troubleshooting.mdx | 17 +++--------- install-flox/uninstall.mdx | 18 ++---------- 3 files changed, 18 insertions(+), 64 deletions(-) diff --git a/install-flox/install.mdx b/install-flox/install.mdx index d2eaec6..8f30113 100644 --- a/install-flox/install.mdx +++ b/install-flox/install.mdx @@ -24,15 +24,12 @@ description: "How to install or upgrade the Flox CLI" curl -fsSL https://get.flox.dev | sh ``` - The script picks an install method in this order: + The script picks the install method that matches your platform: - 1. If Nix is already installed, the script installs Flox through your - existing Nix with `nix profile install` — it does not replace your - Nix, it only adds the Flox cache to `nix.conf`. - 1. On MacOS, it downloads and runs the `.pkg` installer. - 1. On Debian- and Ubuntu-family systems, it installs the `.deb` package + * On MacOS, it downloads and runs the `.pkg` installer. + * On Debian- and Ubuntu-family systems, it installs the `.deb` package with `apt`. - 1. On Fedora- and RHEL-family systems, it installs the `.rpm` package + * On Fedora- and RHEL-family systems, it installs the `.rpm` package with `dnf` or `yum`. If Flox is already installed, the script makes no changes and instead @@ -59,31 +56,14 @@ description: "How to install or upgrade the Flox CLI" ... ``` - - - The script does **not** replace or reconfigure an existing Nix - installation. Instead it installs Flox into your Nix profile: - - 1. Adds the Flox cache (`https://cache.flox.dev`) and its public - signing key to `nix.conf` — system-wide when `sudo` is available, - otherwise user-level — and restarts `nix-daemon` if one is running. - 1. Installs Flox with `nix profile install github:flox/flox/latest`. - - ```console - $ curl -fsSL https://get.flox.dev | sh - ==> Adding the Flox cache (https://cache.flox.dev) to /etc/nix/nix.conf - ==> The following commands will be run with sudo: - sudo mkdir -p /etc/nix - sudo tee -a /etc/nix/nix.conf - ==> The following commands will be run with sudo: - sudo systemctl restart nix-daemon - ==> Nix detected — installing Flox via nix profile install (github:flox/flox/latest) - ... - ``` + + **If Nix is already installed on your system** - If you would rather configure Nix yourself, see the - [Nix (Generic)](#nix-generic) instructions. - + The script does not install Flox through Nix, and it will not modify + your existing Nix installation. When it detects Nix (the `nix` command + or a populated `/nix/store`), it stops and points you to the + [Nix](#nix) tab, which covers installing Flox with an existing Nix. + **Unsupported systems** @@ -91,7 +71,7 @@ description: "How to install or upgrade the Flox CLI" untested: immutable (ostree-based) distributions such as Fedora Silverblue or CoreOS, openSUSE/SLES, and RPM-family systems without `dnf` or `yum`. On those systems, install Nix first and then follow the - [Nix (Generic)](#nix-generic) instructions. + [Nix](#nix) tab instructions. **Pin a channel or version** @@ -105,9 +85,6 @@ description: "How to install or upgrade the Flox CLI" `FLOX_CHANNEL` (default `stable`) selects the release channel. `FLOX_VERSION` pins an exact version instead of the channel's latest. - When Flox is installed through an existing Nix, `FLOX_CHANNEL` is - ignored: the script installs `github:flox/flox/latest`, or - `github:flox/flox/v` when `FLOX_VERSION` is set. **Verify Flox installation** diff --git a/install-flox/troubleshooting.mdx b/install-flox/troubleshooting.mdx index df9d000..1517673 100644 --- a/install-flox/troubleshooting.mdx +++ b/install-flox/troubleshooting.mdx @@ -79,20 +79,11 @@ If you have a partial Flox installation, you can run Flox uninstallation. - The install script installs Flox with your system package manager, or - through Nix if Nix was already present. Follow the tab that matches how - the script installed Flox: [MacOS (Pkg)](#macos-pkg) on MacOS, + The install script installs Flox with your system package manager. + Follow the tab that matches how the script installed Flox: + [MacOS (Pkg)](#macos-pkg) on MacOS, [Debian](#debian) on Debian- and Ubuntu-family systems, or - [RPM](#rpm) on Fedora- and RHEL-family systems. If Flox was installed - through an existing Nix, remove it with: - - ```bash - nix profile remove flox - ``` - - If that reports no matching entry, run `nix profile list` to find the - right name (on older Nix, remove by index or with - `nix profile remove github:flox/flox/latest`). + [RPM](#rpm) on Fedora- and RHEL-family systems. diff --git a/install-flox/uninstall.mdx b/install-flox/uninstall.mdx index 44b368f..00774ac 100644 --- a/install-flox/uninstall.mdx +++ b/install-flox/uninstall.mdx @@ -17,26 +17,12 @@ Here's how to **completely remove `flox` from your system**. - The install script installs Flox with your system package manager, or - through Nix if Nix was already present. Uninstall with the method that - matches how the script installed Flox: + The install script installs Flox with your system package manager. + Uninstall with the method that matches how the script installed Flox: * On MacOS, follow the [MacOS (Pkg)](#macos-pkg) tab. * On Debian- and Ubuntu-family systems, follow the [Debian](#debian) tab. * On Fedora- and RHEL-family systems, follow the [RPM](#rpm) tab. - * If Flox was installed through an existing Nix, remove it from your Nix - profile: - - ```bash - nix profile remove flox - ``` - - If that reports no matching entry, run `nix profile list` to find the - right name (on older Nix, remove by index or with - `nix profile remove github:flox/flox/latest`). - To also remove the cache configuration the script added, - delete the lines under `# Added by the Flox installer (get.flox.dev)` - in `/etc/nix/nix.conf` (or `~/.config/nix/nix.conf`). From 4b213fb177fee4b50a939f2973cf1cfbdb9bc563 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Wed, 5 Aug 2026 11:45:16 -0700 Subject: [PATCH 3/4] docs(install): use real headings in the Install Script tab Promote the tab's bold pseudo-headings to ## headings so Mintlify's tab-aware "On this page" rail navigates the tab, matching the MacOS and Nix tabs. Co-Authored-By: Claude Fable 5 --- install-flox/install.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/install-flox/install.mdx b/install-flox/install.mdx index 8f30113..39934cf 100644 --- a/install-flox/install.mdx +++ b/install-flox/install.mdx @@ -14,7 +14,7 @@ description: "How to install or upgrade the Flox CLI" - **Install with one command** + ## Install with one command The install script detects your OS and CPU architecture and installs Flox with the best method available on your machine. It supports MacOS and @@ -74,7 +74,7 @@ description: "How to install or upgrade the Flox CLI" [Nix](#nix) tab instructions. - **Pin a channel or version** + ## Pin a channel or version The script honors two environment variables: @@ -86,7 +86,7 @@ description: "How to install or upgrade the Flox CLI" `FLOX_CHANNEL` (default `stable`) selects the release channel. `FLOX_VERSION` pins an exact version instead of the channel's latest. - **Verify Flox installation** + ## Verify Flox installation If the following command returns without error then you're ready to get started! @@ -99,7 +99,7 @@ description: "How to install or upgrade the Flox CLI" The version you see might be different. - **Upgrade existing Flox installation** + ## Upgrade existing Flox installation The script does not upgrade an existing installation. Re-running it on a system that already has Flox prints the upgrade command for your package From 4d4ad99c28fabcb8f2b5c07b608513f559c979dc Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Wed, 5 Aug 2026 11:46:32 -0700 Subject: [PATCH 4/4] docs(install): promote the remaining tabs' pseudo-headings to real headings Convert the bold pseudo-headings in the Debian, RPM, Container, and WSL 2 tabs to ## headings so every tab on the page gets Mintlify's tab-aware "On this page" navigation, completing the pattern started for the MacOS and Nix tabs. Bold titles inside accordions are left as-is (headings there don't reach the ToC). Co-Authored-By: Claude Fable 5 --- install-flox/install.mdx | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/install-flox/install.mdx b/install-flox/install.mdx index 39934cf..df532a2 100644 --- a/install-flox/install.mdx +++ b/install-flox/install.mdx @@ -205,7 +205,7 @@ description: "How to install or upgrade the Flox CLI" The package will register a new source in `/etc/apt/sources.list.d` to enable upgrades via `apt`. - **Download and install the package** + ## Download and install the package 1. Download flox.deb for your system architecture: @@ -246,7 +246,7 @@ description: "How to install or upgrade the Flox CLI" The version of Nix installed by Flox tracks the stable version of Nix in nixpkgs, occasionally adding additional backports or patches. Nix is usually updated monthly, although if Nix makes breaking changes, updates may be less frequent. - **Verify Flox installation** + ## Verify Flox installation If the following command returns without error then you're ready to get started! @@ -259,7 +259,7 @@ description: "How to install or upgrade the Flox CLI" The version you see might be different. - **Upgrade existing Flox installation** + ## Upgrade existing Flox installation ``` sudo apt update; @@ -276,7 +276,7 @@ description: "How to install or upgrade the Flox CLI" The rpm will register a package repository in `/etc/yum.repos.d` to enable upgrades. via `yum`, `dnf` and other compatible tools. - **Download and install the package** + ## Download and install the package 1. Download flox.rpm for your system architecture: @@ -318,7 +318,7 @@ description: "How to install or upgrade the Flox CLI" The version of Nix installed by Flox tracks the stable version of Nix in nixpkgs, occasionally adding additional backports or patches. Nix is usually updated monthly, although if Nix makes breaking changes, updates may be less frequent. - **Verify Flox installation** + ## Verify Flox installation If the following command returns without error then you're ready to get started! @@ -331,7 +331,7 @@ description: "How to install or upgrade the Flox CLI" The version you see might be different. - **Upgrade existing Flox installation** + ## Upgrade existing Flox installation ``` sudo yum update flox @@ -617,13 +617,13 @@ description: "How to install or upgrade the Flox CLI" If you have Docker installed then you can also run flox in a container to try it out before installing on your system. - **Invoke Flox container** + ## Invoke Flox container ``` docker run --pull always --rm -it ghcr.io/flox/flox ``` - **Verify Flox installation** + ## Verify Flox installation If the following command returns without error then you're ready to get started! @@ -668,14 +668,14 @@ description: "How to install or upgrade the Flox CLI" * terminate distribution: `wsl --terminate ` * unregister and delete distribution: `wsl --unregister ` - **Supported distributions** + ## Supported distributions Please follow the steps below to install Flox on the distribution of your choice: - **Download and install the package** + ## Download and install the package 1. Download flox.deb for your system architecture: @@ -696,7 +696,7 @@ description: "How to install or upgrade the Flox CLI" sudo apt-get install policycoreutils semodule-utils tar wget xz-utils ``` - **Download and install the package** + ## Download and install the package 1. Download flox.deb for your system architecture: @@ -717,7 +717,7 @@ description: "How to install or upgrade the Flox CLI" sudo yum install tar xz ``` - **Download and install the package** + ## Download and install the package 1. Download flox.rpm for your system architecture: @@ -747,7 +747,7 @@ description: "How to install or upgrade the Flox CLI" You can disregard this message as we will be configuring the `nix-daemon` to start automatically in the next section. - **Configure `nix-daemon` to start on activation** + ## Configure `nix-daemon` to start on activation Once Flox has been installed on your WSL distribution the `nix-daemon` will need to be automatically started as you start your WSL instance. @@ -767,7 +767,7 @@ description: "How to install or upgrade the Flox CLI" ``` nix --extra-experimental-features nix-command store ping ``` - **Verify Flox installation** + ## Verify Flox installation If the following command returns without error then you're ready to get started! @@ -780,7 +780,7 @@ description: "How to install or upgrade the Flox CLI" The version you see might be different. - **Upgrade existing Flox installation** + ## Upgrade existing Flox installation Please follow the instructions provided on either the Debian or RPM tab (whichever matches the existing Linux Distribution installed with your