While the resource requirements for Flox will vary based on the
software you install, we recommend a minimum of 4Gb of memory and 8Gb of
storage to install most software.
Minimum requirements for running installed software is not effected
by Flox.
Existing Nix installations
Use the Flox installer for your system to allow some opinionated configuration of Nix, or use the "Nix - Generic" instructions for full control of your Nix installation.
For use on Debian, Ubuntu, and other Debian-based distributions.
Download and install the package
Note
The package will register a new source in /etc/apt/sources.list.d to enable upgrades via apt.
The Flox installer will perform some opinionated configuration of Nix, but Nix will still be usable.
If you want full control of your Nix installation, see the instructions for installing Flox in the "Nix - Generic" tab above.
When installing over a previous installation of Nix the Flox installation
will:
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
Overwrite the system-wide /etc/nix/nix.conf
(If applicable) convert the Nix installation to a multi-user install
Reconfigure the nix-daemon invocation
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 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.
Verify Flox installation
If the following command returns without error then you're ready to get
started!
$ flox--version1.4.4
Download and install the package that matches your machine's
architecture.
The Flox installer will perform some opinionated configuration of Nix, but Nix will still be usable.
If you want full control of your Nix installation, see the instructions for installing Flox in the "Nix - Generic" tab above.
When installing over a previous installation of Nix the Flox installation
will:
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
Overwrite the system-wide /etc/nix/nix.conf
(If applicable) convert the Nix installation to a multi-user install
Reconfigure the nix-daemon invocation
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 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.
Verify Flox installation
If the following command returns without error then you're ready to get
started!
$ flox--version1.4.4
Note
You may be prompted for a sudo password or be asked if your terminal has authorization to modify disk contents.
In your terminal run:
brew install flox
Replacing an existing Nix installation
The Flox installer will perform some opinionated configuration of Nix, but Nix will still be usable.
If you want full control of your Nix installation, see the instructions for installing Flox in the "Nix - Generic" tab above.
When installing over a previous installation of Nix the Flox installation
will:
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
Overwrite the system-wide /etc/nix/nix.conf
(If applicable) convert the Nix installation to a multi-user install
Reconfigure the nix-daemon invocation
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 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.
Verify Flox installation
If the following command returns without error then you're ready to get
started!
$ flox--version1.4.4
If you have Docker installed then you can also run flox in a container to
try it out before installing on your system.
Use Flox container
The easiest way to run Flox in a container is to run the Flox provided container:
docker run --pull always --rm -it ghcr.io/flox/flox
Install into an existing container
If you need to install Flox into an existing container, you can use the .deb
or .rpm installers.
Note that Flox can only be used as root in containers, unless the container
happens to have systemd installed.
Verify Flox installation
If the following command returns without error then you're ready to get
started!
$ flox--version1.4.4
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:
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):
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, including
a full copy of the command invoked and error encountered.
Install Flox with Nix declaratively
The following example is for a Nix darwin installation.
You may need to modify inputs to match your system.
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.
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.
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.
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!
$ flox--version1.4.4
Configure Substituters
Similarly configure /etc/nixos/configuration.nix to add the lines:
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):
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, including
a full copy of the command invoked and error encountered.
Verify Flox installation
If the following command returns without error then you're ready to get
started!
$ flox--version1.4.4
Support for WSL 2 is experimental.
Install WSL 2
Please install and configure WSL version 2 as described in the
Microsoft Learn Install
WSL
guide before installing Flox. Please also ensure the
state
(whether the distribution is running or stopped) is running.
Note that installation will fail on WSL 1.
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:
You will encounter the following warning during the installation:
---- 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.
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!
$ flox--version1.4.4
Upgrade existing Flox installation
For use on Debian, Ubuntu, and other Debian-based distributions.
For use on RedHat, CentOS, Amazon Linux, and other RPM-based
distributions.
sudo yum update flox
or
sudo dnf update flox
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.
Download and install the latest image as described in the MacOS column
of the install section.
brew upgrade flox
If you've installed Flox to the system-wide default profile
Nix does not always update transitive dependencies when the version is
changed,
so to ensure all updates are applied, run nix flake update.
Uninstall Flox
While we are sad we see you uninstalling flox we would like to thank you
for giving flox a try.
As we try to improve flox we really appreciate any feedback, especially
where we failed. We like to know what was not working or where could we do
a better job. If you can, please reach us via
discourse or via
email.
Here's how to completely remove flox from your system.
For use on Debian, Ubuntu, and other Debian-based distributions.
The following command will completely remove Nix and the contents of /nix/* from the system.
Be sure to back up the system and/or extract any important Nix-related
files and packages before continuing.
sudo apt-get purge flox
We recommend rebooting your system after uninstalling Flox.
For use on RedHat, CentOS, Amazon Linux, and other RPM-based
distributions.
The following command will completely remove Nix and the contents of /nix/* from the system.
Be sure to back up the system and/or extract any important Nix-related
files and packages before continuing.
sudo yum remove flox
We recommend rebooting your system after uninstalling Flox.
Output on success:
$ sudo yum remove flox
Updating Subscription Management repositories.
Unable to read consumer identity
This system is not registered to Red Hat Subscription Management.
You can use subscription-manager to register.
Dependencies resolved.
======================================================================
Package Architecture Version Repository Size
======================================================================
Removing:
flox x86_64 1.4.3-1625910780 @@System 109 M
Transaction Summary
======================================================================
Remove 1 Package
Freed space: 109 M
Is this ok [y/N]: y
Running transaction check
Transaction check succeeded.
Running transaction test
Transaction test succeeded.
Running transaction
Preparing : 1/1
Running scriptlet: flox-1.4.3-1625910780.x86_64 1/1
floxadm uninstall complete
Erasing : flox-1.4.3-1625910780.x86_64 1/1
Running scriptlet: flox-1.4.3-1625910780.x86_64 1/1
Verifying : flox-1.4.3-1625910780.x86_64 1/1
Installed products updated.
Removed:
flox-1.4.3-1625910780.x86_64
Complete!
Please follow the instructions provided on either the Debian or RPM tab
(whichever matches the existing Linux Distribution installed with your
WSL) to uninstall Flox.
The following commands will completely remove Nix and the contents of /nix/* from the system.
Be sure to back up the system and/or extract any important Nix-related
files and packages before continuing.
Ensure no running processes are using /nix.
Run:
sudo /usr/local/share/flox/scripts/uninstall
Regardless of the current state, brew can be used to perform a full clean up:
brew uninstall --force --zap flox
We recommend rebooting your system after uninstalling Flox.
The following commands will completely remove Nix and the contents of /nix/* from the system.
Be sure to back up the system and/or extract any important Nix-related
files and packages before continuing.
You may be asked if the terminal has permission to modify contents of the disk.
Run:
brew uninstall flox
To remove all traces of flox including user preferences uninstall with:
brew uninstall --zap flox
In the case of recovering a partial install, a force and zap can help:
brew uninstall --force --zap flox
We recommend rebooting your system after uninstalling Flox.
If you've installed flox to the system-wide default profile