Managed environments¶

All examples on this page will use my-env as the name of the environment you're working on.

Install packages¶

Given that you want to install packages foo, bar, and baz:

$ flox install -e my-env foo bar baz

If a package comes from a catalog my-catalog you must prefix the package name with my-catalog.:

$ flox install -e my-env my-catalog.foo

Remove packages¶

Given that you want to remove packages foo and bar:

$ flox remove -e my-env foo bar

If a package comes from a catalog my-catalog you must prefix the package name with my-catalog.:

$ flox remove -e my-env my-catalog.foo

List installed packages¶

$ flox list -e my-env

Activate an environment¶

$ flox activate -e my-env
flox [my-env default] $ # (1)!

Note that the shell prompt changes to show that you have entered the environment. It lists both my-env and default. The default environment is always activated when you activate an environment.

Run a single command in an environment¶

Given that you want to run command foo in the environment:

$ flox activate -e my-env -- foo

Manually edit the environment definition¶

Commands like flox install modify a declarative configuration file defining the environment. You can manually edit the environment definition with the flox edit command. See flox.nix configuration for details on the file format.

The command should drop you into an editor with a file that has this format:

{
    # contents here
}

Set environment variables¶

Edit the environment definition with flox edit and add an environmentVariables section with key-value pairs in this format:

{
    # other contents here

    environmentVariables = {
        MYVAR = "foo";
        YOURVAR = "bar";
        OURVAR = "baz";
    };
}

This is a Nix attribute set. See the Nix language guide for more details on the syntax, but key-value pairs are always of the form <name> = <value>;. This entire file is in fact a set of key-value pairs.

Add shell hooks¶

Shell hooks are shell commands that are run right before control is returned to the user when activating an environment. You can use shell hooks to run setup commands, start programs, etc.

Edit the environment definition with flox edit and add a shell.hook section with the shell commands you'd like to execute wrapped in pairs of single quotes:

{
    # other contents here

    shell.hook = ''
        echo "You've entered the environment"
    '';
}

The only exception to normal shell code is that the dollar sign $ needs to be escaped with another pair of single quotes like so:

{
    # other contents here

    shell.hook = ''
        foo=''$(pwd)
    '';
}

Environments are stored as git repositories named floxmeta. First authenticate with GitHub if you haven't already done so:

$ flox gh auth login

This command will ask you questions about which GitHub account to use, which protocol to interact with (https or ssh), etc.

Now push the repository to a git host with flox push:

$ flox push -e my-env

This command will ask you questions about where to host the repository. This repository is set to private by default. If you'd like to share this environment with someone else you'll need to grant that person read access to the repository or make the repository public.

Use someone else's environment¶

Let's say you want to use an environment called their-env from a GitHub user named someone-else. You pull someone else's environment with the flox pull command:

$ flox pull -e someone-else/their-env

You can now activate this environment like you would one of your own, simply prefix it with the other user's GitHub handle:

$ flox activate -e someone-else/their-env