Skip to content
Get Started

Declarative environments

Up to now, we've used imperative ways of configuring environments, but you can also update environments declaratively.

Not only that, instead of only adding packages to the environments, you can also configure other parts of the environment: environment variables, welcome message, ...

If you haven't already, please install flox before continuing.

1. flox edit - open editor to configure environment

flox edit -e example

This command will open flox.nix (an environment configuration file) in an editor. You can configure the EDITOR variable to an editor of your choice.

If the specified environment (example in our case) does not exist, then the environment will be created once we save our changes and exit the editor.

2. Writing flox.nix environment configuration

As the file ending suggests, the language in which environments are configured is the Nix expression language.

For any change to the environment to take an effect, simply update and save the file. For example, you can delete a package by deleting the relevant stanza, and/or install a package by similarly adding a new stanza.

Here is a full example of an environment configuration; click at the end of each line for an explanation.

flox.nix
{
  # Packages
  # "version" is optional, otherwise the latest is used. Try `flox search`
  packages.nixpkgs-flox.figlet = {}; 
  packages.nixpkgs-flox.bat = { version = "0.22.1"; }; # (1)!

  # Aliases available when environment is active
  shell.aliases.cat = "bat"; # (2)!

  # Script run upon environment activation
  shell.hook = ''
    echo Flox Environment | figlet
  ''; # (3)!

  # Environment variables
  environmentVariables.LANG = "en_US.UTF-8"; # (4)!
}

  1. Adding a package with its version specified. When no version is specified the latest version of that package is used.

    To find packages use flox search command.

  2. Setting environment-specific shell aliases.

    An alias is a (usually short) name that the shell translated into another (usually longer) name or command.

  3. Creating a shell hook.

    A shell hook is piece of bash script that gets called when the environment is activated.

  4. Declaring variables that are local to the environment.

This configuration file returns what we call an attribute set, basically just a set of key-value pairs. You can declare nested attributes via a . syntax.

Now lets activate our example environment and see if it's configured correctly.

$ flox activate -e example
 _____ _
|  ___| | _____  __
| |_  | |/ _ \ \/ /
|  _| | | (_) >  <
|_|   |_|\___/_/\_\

 _____            _                                      _
| ____|_ ____   _(_)_ __ ___  _ __  _ __ ___   ___ _ __ | |_
|  _| | '_ \ \ / / | '__/ _ \| '_ \| '_ ` _ \ / _ \ '_ \| __|
| |___| | | \ V /| | | | (_) | | | | | | | | |  __/ | | | |_
|_____|_| |_|\_/ |_|_|  \___/|_| |_|_| |_| |_|\___|_| |_|\__|



flox [example default] $ which bat
/home/USER/.local/share/flox/environments/local/aarch64-linux.example/bin/bat

flox [example default] $ which cat
cat: aliased to bat

flox [example default] $ type cat
cat is an alias for bat

flox [example default] $ echo $LANG
en_US.UTF-8

flox [example default] $ exit
$

Where to next?