> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Flox

> How to install or upgrade the Flox CLI

<Note>
  **Verify your download**

  You can find the
  [SHA256 checksums](https://downloads.flox.dev/by-env/stable/flox-1.13.0.SHA256SUMS) and
  [SHA512 checksums](https://downloads.flox.dev/by-env/stable/flox-1.13.0.SHA512SUMS) for
  Flox 1.13.0 online.
</Note>

<Tabs>
  <Tab title="MacOS (Pkg)">
    **Download and install the package that matches your machine's architecture.**

    1. Download installer for Macs with

           <CardGroup cols={2}>
             <Card title="Apple Silicon" icon="apple" href="https://downloads.flox.dev/by-env/stable/osx/flox-1.13.0.aarch64-darwin.pkg">
               aarch64-darwin
             </Card>

             <Card title="Intel processors" icon="microchip" href="https://downloads.flox.dev/by-env/stable/osx/flox-1.13.0.x86_64-darwin.pkg">
               x86\_64-darwin
             </Card>
           </CardGroup>

    2. Double-click to install the downloaded file

    3. Open a terminal window to continue below

    <Accordion title="This will replace an existing Nix installation">
      Flox will reconfigure an existing Nix installation. These changes are designed to improve the overall user experience and make the Nix installation more reliable and easier to support, but it's worth noting that **anyone wishing to revert to a "vanilla" Nix installation after installing Flox will need to re-install Nix**.

      If you want retain full control of your Nix installation, see the [Nix (Generic)](#nix-generic) instructions.

      ***

      When installing over a previous installation of Nix the Flox installation
      will:

      1. Back out customizations made to the following files when Nix was
         installed:
         * `/etc/bashrc`
         * `/etc/bash.bashrc`
         * `/etc/profile.d/nix.sh`
         * `/etc/zshrc`
         * `/etc/zsh/zshrc`
      2. Overwrite the system-wide `/etc/nix/nix.conf`
      3. (If applicable) convert the Nix installation to a multi-user install
      4. Reconfigure the `nix-daemon` invocation

      If you are installing over a previous installation of Nix we suggest that you install Flox to a test machine or VM to gain familiarity with it first.

      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.
    </Accordion>

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.

    **Upgrades to existing Flox installation**

    Download and install the latest image as described above.
  </Tab>

  <Tab title="MacOS (Homebrew)">
    **Brew install**

    In your terminal run:

    ```
    brew install flox
    ```

    <Note>
      **Note**

      You may be prompted for a `sudo` password or be asked if your terminal has authorization to modify disk contents.
    </Note>

    <Accordion title="This will replace an existing Nix installation">
      Flox will reconfigure an existing Nix installation. These changes are designed to improve the overall user experience and make the Nix installation more reliable and easier to support, but it's worth noting that **anyone wishing to revert to a "vanilla" Nix installation after installing Flox will need to re-install Nix**.

      If you want retain full control of your Nix installation, see the [Nix (Generic)](#nix-generic) instructions.

      ***

      When installing over a previous installation of Nix the Flox installation
      will:

      1. Back out customizations made to the following files when Nix was
         installed:
         * `/etc/bashrc`
         * `/etc/bash.bashrc`
         * `/etc/profile.d/nix.sh`
         * `/etc/zshrc`
         * `/etc/zsh/zshrc`
      2. Overwrite the system-wide `/etc/nix/nix.conf`
      3. (If applicable) convert the Nix installation to a multi-user install
      4. Reconfigure the `nix-daemon` invocation

      If you are installing over a previous installation of Nix we suggest that you install Flox to a test machine or VM to gain familiarity with it first.

      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.
    </Accordion>

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.

    **Upgrade existing Flox installation**

    ```
    brew upgrade flox
    ```
  </Tab>

  <Tab title="Debian">
    For use on Debian, Ubuntu, and other Debian-based distributions.

    <Note>
      **Note**

      The package will register a new source in `/etc/apt/sources.list.d` to enable upgrades via `apt`.
    </Note>

    **Download and install the package**

    1. Download flox.deb for your system architecture:

       [64-bit Intel/AMD](https://downloads.flox.dev/by-env/stable/deb/flox-1.13.0.x86_64-linux.deb)
       [64-bit ARM](https://downloads.flox.dev/by-env/stable/deb/flox-1.13.0.aarch64-linux.deb)

    2. Install the downloaded file

       ```
       sudo apt install /path/to/flox.deb
       ```

    <Accordion title="This will replace an existing Nix installation">
      Flox will reconfigure an existing Nix installation. These changes are designed to improve the overall user experience and make the Nix installation more reliable and easier to support, but it's worth noting that **anyone wishing to revert to a "vanilla" Nix installation after installing Flox will need to re-install Nix**.

      If you want retain full control of your Nix installation, see the [Nix (Generic)](#nix-generic) instructions.

      ***

      When installing over a previous installation of Nix the Flox installation
      will:

      1. Back out customizations made to the following files when Nix was
         installed:
         * `/etc/bashrc`
         * `/etc/bash.bashrc`
         * `/etc/profile.d/nix.sh`
         * `/etc/zshrc`
         * `/etc/zsh/zshrc`
      2. Overwrite the system-wide `/etc/nix/nix.conf`
      3. (If applicable) convert the Nix installation to a multi-user install
      4. Reconfigure the `nix-daemon` invocation

      If you are installing over a previous installation of Nix we suggest that you install Flox to a test machine or VM to gain familiarity with it first.

      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.
    </Accordion>

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.

    **Upgrade existing Flox installation**

    ```
    sudo apt update;
    sudo apt --only-upgrade install flox
    ```
  </Tab>

  <Tab title="RPM">
    For use on RedHat, CentOS, Amazon Linux, and other RPM-based distributions.

    <Note>
      **Note**

      The rpm will register a package repository in `/etc/yum.repos.d` to enable upgrades.
      via `yum`, `dnf` and other compatible tools.
    </Note>

    **Download and install the package**

    1. Download flox.rpm for your system architecture:

       [64-bit Intel/AMD](https://downloads.flox.dev/by-env/stable/rpm/flox-1.13.0.x86_64-linux.rpm)
       [64-bit ARM](https://downloads.flox.dev/by-env/stable/rpm/flox-1.13.0.aarch64-linux.rpm)

    2. Install the downloaded file

       ```
       sudo rpm --import https://downloads.flox.dev/by-env/stable/rpm/flox-archive-keyring.asc
       sudo rpm -ivh /path/to/flox.rpm
       ```

    <Accordion title="This will replace an existing Nix installation">
      Flox will reconfigure an existing Nix installation. These changes are designed to improve the overall user experience and make the Nix installation more reliable and easier to support, but it's worth noting that **anyone wishing to revert to a "vanilla" Nix installation after installing Flox will need to re-install Nix**.

      If you want retain full control of your Nix installation, see the [Nix (Generic)](#nix-generic) instructions.

      ***

      When installing over a previous installation of Nix the Flox installation
      will:

      1. Back out customizations made to the following files when Nix was
         installed:
         * `/etc/bashrc`
         * `/etc/bash.bashrc`
         * `/etc/profile.d/nix.sh`
         * `/etc/zshrc`
         * `/etc/zsh/zshrc`
      2. Overwrite the system-wide `/etc/nix/nix.conf`
      3. (If applicable) convert the Nix installation to a multi-user install
      4. Reconfigure the `nix-daemon` invocation

      If you are installing over a previous installation of Nix we suggest that you install Flox to a test machine or VM to gain familiarity with it first.

      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.
    </Accordion>

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.

    **Upgrade existing Flox installation**

    ```
    sudo yum update flox
    ```

    or

    ```
    sudo dnf update flox
    ```
  </Tab>

  <Tab title="Nix (Generic)">
    <Note>
      **Which install method for existing Nix installation?**

      Use the Flox installer for your system to allow some opinionated configuration of Nix, or use these "Nix (Generic)" instructions for full control of your Nix installation.
    </Note>

    **Install Nix**

    Please ensure you are using Nix version `2.18.0` or greater.

    **Install Flox with Nix imperatively**

    * Configure Substituters

      Add the following values to `/etc/nix/nix.conf`, taking care to merge them
      with any `trusted-substituters` or `trusted-public-keys` values that may
      already be defined:

      ```bash title="/etc/nix/nix.conf" theme={null}
      extra-trusted-substituters = https://cache.flox.dev
      extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=
      ```

      Then restart the `nix-daemon`, if applicable:

      * Linux:
        ```
        sudo systemctl stop nix-daemon.service
        sudo systemctl restart nix-daemon.socket
        ```
      * MacOS:
        ```
        sudo launchctl kickstart -k -p system/org.nixos.nix-daemon
        ```

    * Install Flox to your *personal* profile:

      ```
      nix profile install \
            --experimental-features "nix-command flakes" \
            --accept-flake-config \
            'github:flox/flox/latest'
      ```

    * Install Flox to the system-wide `default` profile as root:

      ```
      sudo -H nix profile install \
            --profile /nix/var/nix/profiles/default \
            --experimental-features "nix-command flakes" \
            --accept-flake-config \
            'github:flox/flox/latest'
      ```

    <Accordion title="On error">
      If you encounter the following error then please upgrade your Nix
      installation (and in particular the running `nix-daemon`) to the latest
      version (minimum supported version is `2.18.0`):

      ```text theme={null}
      error: builder for '/nix/store/35l1qqyis11y88ic0cp3yxgv3286l4pb-flox-0.0.2-r295.drv' failed with exit code 1;
             last 1 log lines:
             > error: attribute 'requisites' missing
      ```

      If you encounter any other errors with the installer please report the
      bug by way of [discourse](https://discourse.flox.dev), including
      a full copy of the command invoked and error encountered.
    </Accordion>

    **Install Flox with Nix declaratively**

    The following example is for a Nix darwin installation.
    You may need to modify inputs to match your system.

    <Accordion title="Using Flox's binary cache">
      Flox hosts a binary cache for its packages, that can be added to your `/etc/nix/nix.conf` file.
      We recommend doing this if you are installing Flox system-wide.

      ```bash title="/etc/nix/nix.conf" theme={null}
      extra-trusted-substituters = https://cache.flox.dev
      extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=
      ```

      Or, to your flake configuration by using the `nixConfig` attribute.
      This will ensure that Flox's binary cache is used for all operation within that flake.

      ```nix title="flake.nix" theme={null}
      {
          nixConfig = {
              extra-trusted-substituters = ["https://cache.flox.dev"];
              extra-trusted-public-keys = ["flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs="];
          };
      }
      ```

      Note that if you don't add either of these options, Flox will be built from source, together with a patched version of Nix.
      Which might take a while on less powerful systems.
    </Accordion>

    ```nix theme={null}
    {
      description = "Example Darwin system flake";

      nixConfig = {
        extra-trusted-substituters = ["https://cache.flox.dev"];
        extra-trusted-public-keys = ["flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs="];
      };

      inputs = {
        nixpkgs = {
          url = "github:NixOS/nixpkgs/nixpkgs-23.11-darwin";
        };
        nix-darwin = {
          url = "github:LnL7/nix-darwin";
          inputs.nixpkgs.follows = "nixpkgs";
        };
        flox = {
          url = "github:flox/flox/latest";
        };
      };

      outputs = inputs@{ self, nix-darwin, nixpkgs, flox }:
      let
        configuration = { pkgs, ... }: {
          environment.systemPackages =
            [ pkgs.__YOUR_PACKAGES__
              inputs.flox.packages.${pkgs.system}.default
            ];

          nix.settings = {
            experimental-features = "nix-command flakes";
            substituters = [
              "https://cache.flox.dev"
            ];
            trusted-public-keys = [
              "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs="
            ];
          };

          __YOUR_CONFIG__
        };
      in
      {
        darwinConfigurations."__YOUR_HOST__" = nix-darwin.lib.darwinSystem {
          modules = [ configuration ];
          specialArgs = { inherit inputs; };
        };
      };
    }

    ```

    Run `nix-darwin` to install the configuration and packages you’ve declared.
    This is an example on `nix-darwin`: `nix run nix-darwin -- switch --flake ~/path/to/flake`

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.

    **Upgrade existing Flox installation**

    If you've installed Flox to the system-wide `default` profile

    ```
    sudo -H nix profile upgrade \
            --profile /nix/var/nix/profiles/default \
            --experimental-features "nix-command flakes" \
            --accept-flake-config \
            '.*flox'
    ```

    Or, if you've installed Flox to your own *personal* profile

    ```
    nix profile upgrade \
        --experimental-features "nix-command flakes" \
        --accept-flake-config \
        '.*flox'
    ```

    Or, if you've declared Flox using a flake, run `nix flake update`.
  </Tab>

  <Tab title="Nix (NixOS)">
    **Configure Substituters**

    Similarly configure `/etc/nixos/configuration.nix` to add the lines:

    ```text title="/etc/nixos/configuration.nix" theme={null}
    nix.settings.trusted-substituters = [ "https://cache.flox.dev" ];
    nix.settings.trusted-public-keys = [ "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" ];
    ```

    ... and then invoke:

    ```
    sudo nixos-rebuild switch
    ```

    **Install Flox**

    * Install to your *personal* profile:

      ```
      nix profile install \
            --experimental-features "nix-command flakes" \
            --accept-flake-config \
            'github:flox/flox/latest'
      ```

    * Install Flox to the system-wide `default` profile as root:

      ```
      sudo -H nix profile install \
            --profile /nix/var/nix/profiles/default \
            --experimental-features "nix-command flakes" \
            --accept-flake-config \
            'github:flox/flox/latest'
      ```

    <Accordion title="On error">
      If you encounter the following error then please upgrade your Nix
      installation (and in particular the running `nix-daemon`) to the latest
      version (minimum supported version is `2.18.0`):

      ```text theme={null}
      error: builder for '/nix/store/35l1qqyis11y88ic0cp3yxgv3286l4pb-flox-0.0.2-r295.drv' failed with exit code 1;
             last 1 log lines:
             > error: attribute 'requisites' missing
      ```

      If you encounter any other errors with the installer please report the
      bug by way of [discourse](https://discourse.flox.dev), including
      a full copy of the command invoked and error encountered.
    </Accordion>

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.
  </Tab>

  <Tab title="Container">
    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**

    ```
    docker run --pull always --rm -it ghcr.io/flox/flox
    ```

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.
  </Tab>

  <Tab title="WSL 2">
    <Warning>
      **Support for WSL 2 is experimental.**
    </Warning>

    <Info>
      **Install WSL 2**

      Please install and configure **WSL version 2** as described in the
      Microsoft Learn [Install
      WSL](https://learn.microsoft.com/en-us/windows/wsl/install)
      guide before installing Flox. Please also [ensure the
      state](https://learn.microsoft.com/en-us/windows/wsl/basic-commands)
      (whether the distribution is running or stopped) is running.

      Note that installation will fail on WSL 1.
    </Info>

    Microsoft provides several Linux distributions for use with WSL and will
    use Ubuntu by default. Use the following commands to run and manage your
    chosen distribution:

    * list installed distributions: `wsl --list`
    * run specified distribution: `wsl --distribution <name>`
    * list all available distributions: `wsl --list --online`
    * install distribution: `wsl --install -d <name>`
    * terminate distribution: `wsl --terminate <name>`
    * unregister and delete distribution: `wsl --unregister <name>`

    **Supported distributions**

    Please follow the steps below to install Flox on the distribution of your
    choice:

    <Accordion title="Ubuntu">
      **Download and install the package**

      1. Download flox.deb for your system architecture:

         [64-bit Intel/AMD](https://downloads.flox.dev/by-env/stable/deb/flox-1.13.0.x86_64-linux.deb)
         [64-bit ARM](https://downloads.flox.dev/by-env/stable/deb/flox-1.13.0.aarch64-linux.deb)

      2. Install the downloaded file

         ```
         sudo dpkg -i /path/to/flox.deb
         ```
    </Accordion>

    <Accordion title="Debian">
      **Install prerequisites**

      ```
      sudo apt-get install policycoreutils semodule-utils tar wget xz-utils
      ```

      **Download and install the package**

      1. Download flox.deb for your system architecture:

         [64-bit Intel/AMD](https://downloads.flox.dev/by-env/stable/deb/flox-1.13.0.x86_64-linux.deb)
         [64-bit ARM](https://downloads.flox.dev/by-env/stable/deb/flox-1.13.0.aarch64-linux.deb)

      2. Install the downloaded file

         ```
         sudo dpkg -i /path/to/flox.deb
         ```
    </Accordion>

    <Accordion title="OracleLinux_8_5">
      **Install prerequisites**

      ```
      sudo yum install tar xz
      ```

      **Download and install the package**

      1. Download flox.rpm for your system architecture:

         [64-bit Intel/AMD](https://downloads.flox.dev/by-env/stable/rpm/flox-1.13.0.x86_64-linux.rpm)
         [64-bit ARM](https://downloads.flox.dev/by-env/stable/rpm/flox-1.13.0.aarch64-linux.rpm)

      2. Install the downloaded file

         ```
         sudo rpm -ivh /path/to/flox.rpm
         ```
    </Accordion>

    <Info>
      **Ignore warning about systemd**

      You will encounter the following warning during the installation:

      ```text theme={null}
      ---- warning! ------------------------------------------------------------------
      We did not detect systemd on your system. With a multi-user install
      without systemd you will have to manually configure your init system to
      launch the Nix daemon after installation.
      ```

      You can disregard this message as we will be configuring the
      `nix-daemon` to start automatically in the next section.
    </Info>

    **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.

    Run the following command to add the necessary logic to invoke `nix-daemon`
    by way of your `~/.bashrc` file:

    ```
    cat >> ~/.bashrc <<EOF
    ( wsl.exe -d $WSL_DISTRO_NAME -u root service nix-daemon status 2>&1 >/dev/null ) || wsl.exe -d $WSL_DISTRO_NAME -u root service nix-daemon start
    EOF
    ```

    Then restart your WSL shell (or start another) and run the following
    command to ensure that the `nix-daemon` is working correctly:

    ```
    nix --extra-experimental-features nix-command store ping
    ```

    **Verify Flox installation**

    If the following command returns without error then you're ready to get
    started!

    ```console theme={null}
    $ flox --version
    1.13.0

    ```

    The version you see might be different.

    **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
    WSL) to update to latest version of Flox.
  </Tab>
</Tabs>