Skip to content

flox command

flox - command-line interface (CLI)


flox [ <options> ] command [ <command options> ] [ <args> ] …


flox is a platform for developing, building, and using packages created with Nix. It can be used alone to simplify the process of working with Nix, within a team for the sharing of development environments, and in enterprises as system development lifecycle (SDLC) framework.

The flox CLI is used:

  1. To manage and use collections of packages, environment variables and services known as flox runtime environments, which can be used in a variety of contexts on any Linux distribution, in or out of a container.
  2. To launch flox development environments as maintained using a flox.toml file stored within a project directory.
  3. As a wrapper for Nix functionality which drives the process of building packages with flox.

Command Line Completions

Flox ships with command line completions for bash, zsh and fish. To enable completions in your shell Add the following to your shell’s startup script:

When using the flox installers

  • bash, zsh
export XDG_DATA_DIRS="/usr/local/share:$XDG_DATA_DIRS"
  • fish
set -px XDG_DATA_DIRS "/usr/local/share"

When installing flox through Nix

  • bash, zsh
# for single user user installs
export XDG_DATA_DIRS="$HOME/.nix-profile/share:$XDG_DATA_DIRS"

# for global installs
export XDG_DATA_DIRS="/nix/var/nix/profiles/default:$XDG_DATA_DIRS"
  • fish
# for single user user installs
set -px XDG_DATA_DIRS "$HOME/.nix-profile/share"

# for global installs
set -px XDG_DATA_DIRS "/nix/var/nix/profiles/default"


General Options

Many flox commands wrap Nix commands of the same name, and will correspondingly pass on options and arguments directly to the underlying nix invocation. For more information on the options supported by specific Nix commands please invoke flox nix <command> help.

The following options are used specifically by flox and must be specified before the <command> argument.

-v, --verbose
Verbose mode. Invoke multiple times for increasing detail.

Debug mode. Invoke multiple times for increasing detail.

-V, --version
Print flox version.

Print flox installation prefix / Nix store path. (flox internal use only.)

Force execution in flox-bash (flox internal use only.)


Flox commands are grouped into categories pertaining to runtime environments, developer environments, and administration.


List channel subscriptions.

subscribe [ <name> [ <url> ] ]
Subscribe to a flox package channel. If provided, will register the name to the provided URL, and will otherwise prompt with suggested values.

unsubscribe [ <name> ]
Unsubscribe from the named channel. Will prompt for the channel name if not provided.

search <name> [ (-c|--channel) <channel> ] [ --refresh ]
Search for available packages matching name.

Runtime environments

install <package> [ <package> … ]
Install package(s) to environment.

upgrade <package> [ <package> … ]
Upgrade package(s) in environment.

remove [ --force ] <package> [ <package> … ]
Remove package(s) from environment.

Import declarative environment manifest as new generation.

Export environment as a tar.

Export environment as a container image.

Edit declarative environment manifest.

List all environments.

List generations of selected environment.

list [ <generation> ]
List contents of selected environment.

history [ --oneline ]
List history of selected environment.

Sets environment variables and aliases, runs hooks and adds environment bin directories to your $PATH.

push / pull [ --force ]
(git) Push or pull metadata to the environment’s floxmeta repository.

destroy [ --origin ] [ --force ]
Remove all local data pertaining to an environment.


Build the requested package (or “installable”).

Launch subshell configured for development environment using the flox.toml or Nix expression file as found in the current directory.

Perform a build, (optionally) copy binaries to a cache, and add package metadata to a flox channel.

Run flake application from the requested package (or “installable”).


config [ (–list|-l) (–confirm|-c) (–reset|-r) ]
Configure and/or display user-specific parameters.

git <git-subcommand> [ <args> ]
Direct access to git command invoked in the floxmeta repository clone.

gh <gh-subcommand> [ <args> ]
Direct access to gh command. For expert use only.


Flox package arguments are specified as a tuple of stability, channel, name, and version in the format: <stability>.<channel>.<name>@<version>

The version field is optional, defaulting to the latest version if not specified.

The stability field is also optional, defaulting to “stable” if not specified.

The channel field is also optional, defaulting to “nixpkgs-flox” if not specified, but only if using the “stable” stability. If using anything other than the default “stable” stability, the channel must be specified.

For example, each of the following will install the latest hello version 2.12 from the stable channel:

flox install stable.nixpkgs-flox.hello@2.12
flox install stable.nixpkgs-flox.hello
flox install nixpkgs-flox.hello@2.12
flox install nixpkgs-flox.hello
flox install hello@2.12
flox install hello

… and each of the following will install the older hello version 2.10 from the stable channel:

flox install stable.nixpkgs-flox.hello@2.10
flox install nixpkgs-flox.hello@2.10
flox install hello@2.10

… but only the following will install the older hello version 2.10 from the unstable channel:

flox install unstable.nixpkgs-flox.hello@2.10


Location for runtime flox environments as included in PATH environment variable. Defaults to $XDG_DATA_HOME/flox/environments or $HOME/.local/share/flox/environments if $XDG_DATA_HOME is not defined.

By default flox will check for new environment generations in the background as they are activated and then prompt to upgrade with the next activation. This can be configured as follows:

Setting FLOX_AUTOUPDATE=0 disables feature.
Setting FLOX_AUTOUPDATE=1 (or if not defined) enables feature.
Setting FLOX_AUTOUPDATE=2 configures flox to automatically pull updates without prompting.

The FLOX_PROMPT variable defaults to a bold blue “flox” and can be used to specify an alternate flox indicator string (including fancy colors, if desired). For example, include the following in your ~/.bashrc and/or ~/.zshprofile (or equivalent) to display the flox indicator in bold green:

bash: export FLOX_PROMPT="\[\]flox\[\] "
zsh: export FLOX_PROMPT='%B%F{green}flox%f%b '

If you’re just looking to pick different colors, the FLOX_PROMPT_COLOR_1 and FLOX_PROMPT_COLOR_2 variables can be used to select the color of the “flox” and activated environments portions of the prompt, respectively. The values of these variables should be integers chosen from the 256-color palette as described in the xterm-256color chart. For example, setting FLOX_PROMPT_COLOR_1=32 will result in the same prompt as in the examples above.

If defined, the FLOX_PROMPT_DISABLE variable prevents flox from performing all prompt customization for interactive shells.

Setting FLOX_VERBOSE=1 is the same as invoking flox with the --verbose argument except that it can be convenient to set this in the environment for the purposes of development.

Setting FLOX_DEBUG=1 is the same as invoking flox with the --debug argument except that it activates debugging prior to the start of argument parsing and that it can be convenient to set this in the environment for the purposes of development.

Location for the flox metrics accumulator file. Defaults to $XDG_DATA_HOME/.cache/metrics-events or $HOME/.cache/metrics-events if $XDG_DATA_HOME is not defined.

Variable for disabling the collection/sending of metrics data. If set to “true”, prevents flox from submitting basic metrics information including the subcommand issued along with a unique token.

Override the default editor used for editing environment manifests and commit messages.

If set, overrides the path to the default flox-provided SSL certificate bundle. Set NIX_SSL_CERT_FILE to only override packages built with Nix, and otherwise set SSL_CERT_FILE to override the value for all packages.

See also:



flox-activate(1), flox-build(1), flox-channels(1), flox-config(1), flox-containerize(1), flox-create(1), flox-destroy(1), flox-develop(1), flox-edit(1), flox-environments(1), flox-export(1), flox-generations(1), flox-gh(1), flox-git(1), flox-history(1), flox-import(1), flox-init(1), flox-install(1), flox-list(1), flox-print-dev-env(1), flox-publish(1), flox-pull(1), flox-push(1), flox-remove(1), flox-run(1), flox-search(1), flox-subscribe(1), flox-unsubscribe(1), flox-upgrade(1)