flox.nix configuration

These options are valid when editing an environment with flox edit or in a flox.nix file in a project.

The implementation and documentation for these options is in flox/floxpkgs, and any contributions are welcome.

container.config

Run-time configuration of the container. A full list of the options available is in the Docker Image Specification v1.2.0. Note that config.env is not supported (use environmentVariables instead).

If config.entrypoint is not specified, flox activation will be performed in a bash shell.

Type

anything

Default

{ }

container.created

Date and time the layers were created.

Type

string

Default

"1970-01-01T00:00:02Z"

container.extraCommands

Shell commands to run while building the final layer when the environment is transformed into a container. The commands do not have access to most of the layer contents. Changes to this layer are "on top" of all the other layers, so can create additional directories and files.

Type

strings concatenated with "\n"

Default

""

container.maxLayers

Maximum number of layers to create. At most 125

Type

signed integer

Default

100

container.name

The name of the resulting image.

Type

string

Default

"environment name"

container.tag

Tag of the generated image.

Type

string

Default

"latest"

environmentVariables

A set of environment variables. The value of each variable can be either a string or a list of strings. The latter is concatenated, interspersed with colon characters.

Alternatively, this may be a list of sets of environment variables. In that case, order of the variables is preserved, and values are not escaped, which means variables may be evaluated at runtime.

Type

(attribute set of (string or list of string)) or list of attribute set of (string or list of string)

Default

{ }

Example

{
  EDITOR = "nvim";
  VISUAL = "nvim";
}

inline

Escape hatch to inline Nix expressions for packages. The syntax is identical to what can be put in a toplevel flake.nix as an argument to flox-floxpkgs.project; see this template for more details. In general, the top-level packages attribute should be used instead of inline.packages whenever possible.

Type

unspecified value

Default

{ }

Example

{
  packages = {
    myPython = {python3}:
      python3.withPackages (pythonPackages: with pythonPackages; [pandas]);
  };
}

integrations

Alias of {option}inline.

Type

unspecified value

packages

Packages to include in the environment. A number of formats are supported:

• <channel>.<name>

  • <channel> can be any channel subscribed to; run flox channels to list current subscriptions
  • The value of <channel>.<name> must be an attribute set with the following optional attributes:
    • version and stability strings. Available versions and stabilities can be found with flox search -c <channel> <name>.
    • meta.priority, which must be a number and defaults to 5, allows resolving conflicts between two packages that provide the same file. For example, if two packages both provide a binary foo but one package has priority set to 4, that package's version of foo will be present in the environment.
  • A complete example is:

    packages.nixpkgs-flox.hello = {
      stability = "unstable";
      version = "2.12.1";
      meta.priority = 4;
    };
    

• <self>.<name> This installs a package defined in the same project as a flox environment, for example in pkgs/my-pkg/default.nix.

• <flake>.<name> This supports installing packages from an arbitrary Nix flake. In general, installing from a channel is more performant, but this can be useful to use Nix software packaged in a flake that has not yet been packaged for flox.

Type

attribute set of anything

Default

{ }

Example

{
  "github:vlinkz/nix-editor" = {
    nixeditor = { };
  };
  nixpkgs-flox = {
    ripgrep = {
      stability = "unstable";
      version = "13.0.0";
    };
  };
  self = {
    my-pkg = { };
  };
}

shell.aliases

An attribute set that maps aliases (the top level attribute names in this option) to command strings.

Aliases can also be mapped directly to packages, and aliases mapped to null are ignored.

Type

attribute set of (null or string or path)

Default

{ }

Example

{
  ll = "ls -l";
}

shell.hook

Shell script code called during environment activation. This code is assumed to be shell-independent, which means you should stick to pure sh without sh word split.

Type

strings concatenated with "\n"

Default

""

Example

''
  echo "Supercharged by flox!" 1>&2
''