Flox Build System Guide

Build System Overview

Flox supports two build modes, each with its own strengths:

Manifest builds enable you to define your build steps in your manifest and reuse your existing build scripts and toolchains. Flox manifests are declarative artifacts, expressed in TOML.

Manifest builds:

• Make it easy to get started, requiring few if any changes to your existing workflows
• Can run inside a sandbox (using

  sandbox = "pure"

  ) for reproducible builds
• Are best for getting going fast with existing projects

Nix expression builds guarantee build-time reproducibility because they're both isolated and purely functional. Their learning curve is steeper because they require proficiency with the Nix language.

Nix expression builds:

• Are isolated by default. The Nix sandbox seals the build off from the host system, so no state leak ins
• Are functional. A Nix build is defined as a pure function of its declared inputs

You can mix both approaches in the same project, but package names must be unique.

Core Commands

flox build                      # Build all targets
flox build app docs             # Build specific targets
flox build -d /path/to/project  # Build in another directory
flox build -v                   # Verbose output
flox build .#hello              # Build specific Nix expression

Development vs Runtime: The Two-Environment Pattern

A common workflow involves two separate environments:

Development Environment (Build-Time)

Contains source code, build tools, and build definitions:

# project-dev/.flox/env/manifest.toml (in git with source code)
[install]
gcc.pkg-path = "gcc13"
make.pkg-path = "make"
python.pkg-path = "python311Full"
uv.pkg-path = "uv"

[build.myapp]
command = '''
  make build
  mkdir -p $out/bin
  cp build/myapp $out/bin/
'''
version = "1.0.0"

Workflow:

cd project-dev
flox activate
flox build myapp
flox publish -o myorg myapp

Runtime Environment (Consume-Time)

Contains only the published package and runtime dependencies:

# project-runtime/.flox/env/manifest.toml (can push to FloxHub)
[install]
myapp.pkg-path = "myorg/myapp"  # The published package

Workflow:

cd project-runtime
flox init
flox install myorg/myapp
flox push  # Share runtime environment without source code

Why separate environments?

• Development environment: Heavy (build tools, source code, dev dependencies)
• Runtime environment: Lightweight (only published package and runtime needs)
• Security: Runtime environments don't expose source code
• Clarity: Clear separation between building and consuming
• Rollback: Can rollback the live generation of a runtime environment without affecting the development environment

Note: You can also install published packages into existing environments (other projects, production environments, etc.), not just dedicated runtime environments.

Manifest Builds

Flox treats a manifest build as a short, deterministic Bash script that runs inside an activated environment and copies its deliverables into

$out

Critical insights from real-world packaging:

• Build hooks don't run:

  [hook]

  scripts DO NOT execute during

  flox build

  - only during interactive

  flox activate

• Guard env vars: Always use

  ${FLOX_ENV_CACHE:-}

  with default fallback in hooks to avoid build failures
• Wrapper scripts pattern: Create launcher scripts in

  $out/bin/

  that set up runtime environment:

  cat > "$out/bin/myapp" << 'EOF'
  #!/usr/bin/env bash
  APP_ROOT="$(dirname "$(dirname "$(readlink -f "$0")")")"
  export PYTHONPATH="$APP_ROOT/share/myapp:$PYTHONPATH"
  exec python3 "$APP_ROOT/share/myapp/main.py" "$@"
  EOF
  chmod +x "$out/bin/myapp"
  

• User config pattern: Default to

  ~/.myapp/

  for user configs, not

  $FLOX_ENV_CACHE

  (packages are immutable)
• Model/data directories: Create user directories at runtime, not build time:

  mkdir -p "${MYAPP_DIR:-$HOME/.myapp}/models"
  

• Python package strategy: Don't bundle Python deps - include

  requirements.txt

  and setup script:

  # In build, create setup script:
  cat > "$out/bin/myapp-setup" << 'EOF'
  venv="${VENV:-$HOME/.myapp/venv}"
  uv venv "$venv" --python python3
  uv pip install --python "$venv/bin/python" -r "$APP_ROOT/share/myapp/requirements.txt"
  EOF
  

• Dual-environment workflow: Use one environment for building (

  project-dev/

  ), another for consuming (

  project-runtime/

  ). See "Development vs Runtime: The Two-Environment Pattern" section above for details.

Build Definition Syntax

[build.<name>]
command      = '''  # required – Bash, multiline string
  <your build steps>                 # e.g. cargo build, npm run build
  mkdir -p $out/bin
  cp path/to/artifact $out/bin/<name>
'''
version      = "1.2.3"               # optional
description  = "one-line summary"    # optional
sandbox      = "pure" | "off"        # default: off
runtime-packages = [ "id1", "id2" ]  # optional

One table per package. Multiple

[build.*]

Bash only. The script executes under

set -euo pipefail

Environment parity. Before your script runs, Flox performs the equivalent of

flox activate

[install]

Package groups and builds. Only packages in the

toplevel

pkg-group

toplevel

Referencing other builds.

${other}

$out

[build.other]

Purity and Sandbox Control

"off"

"pure"

Pure mode highlights undeclared inputs early and is mandatory for builds intended for CI/CD publication. When a pure build needs pre-fetched artifacts (e.g. language modules) use a two-stage pattern:

[build.deps]
command  = '''go mod vendor -o $out/etc/vendor'''
sandbox  = "off"

[build.app]
command  = '''
  cp -r ${deps}/etc/vendor ./vendor
  go build ./...
  mkdir -p $out/bin
  cp app $out/bin/
'''
sandbox  = "pure"

$out Layout and Filesystem Hierarchy

Only files placed under

$out

$out/bin

$out/sbin

chmod +x

$out/lib

$out/libexec

$out/share/man

$out/etc

Scripts or binaries stored elsewhere will not end up on callers' paths.

Running Manifest Builds

# Build every target in the manifest
flox build

# Build a subset
flox build app docs

# Build a manifest in another directory
flox build -d /path/to/project

Results appear as immutable symlinks:

./result-<name>

/nix/store/...-<name>-<version>

To execute a freshly built binary:

./result-app/bin/app

Multi-Stage Examples

Rust release binary plus source tar

[build.bin]
command = '''
  cargo build --release
  mkdir -p $out/bin
  cp target/release/myproject $out/bin/
'''
version = "0.9.0"

[build.src]
command = '''
  git archive --format=tar HEAD | gzip > $out/myproject-${bin.version}.tar.gz
'''
sandbox = "pure"

${bin.version}

Go with vendored dependencies

[build.vendor]
command = '''
  go mod vendor
  mkdir -p $out/vendor
  cp -r vendor/* $out/vendor/
'''
sandbox = "off"

[build.app]
command = '''
  cp -r ${vendor}/vendor ./
  go build -mod=vendor -o $out/bin/myapp
'''
sandbox = "pure"

Trimming Runtime Dependencies

By default, every package in the

toplevel

Declare a minimal list instead:

[install]
clang.pkg-path = "clang"
pytest.pkg-path = "pytest"

[build.cli]
command = '''
  make
  mv build/cli $out/bin/
'''
runtime-packages = [ "clang" ]  # exclude pytest from runtime closure

Smaller closures copy faster and occupy less disk when installed on users' systems.

Version and Description Metadata

Flox surfaces these fields in

flox search

flox show

[build.mytool]
version.command = "git describe --tags"
description = "High-performance log shipper"

Alternative forms:

version = "1.4.2"            # static string
version.file = "VERSION.txt" # read at build time

Cross-Platform Considerations for Manifest Builds

flox build

linux-x86_64 → build → publish
darwin-aarch64 → build → publish

The manifest can remain identical across hosts.

Beyond Code — Packaging Assets

Any artifact that can be copied into

$out

Nginx baseline config

[build.nginx_cfg]
command = '''mkdir -p $out/etc && cp nginx.conf $out/etc/'''

Organization-wide .proto schema bundle

[build.proto]
command = '''
  mkdir -p $out/share/proto
  cp proto/**/*.proto $out/share/proto/
'''

Teams install these packages and reference them via

$FLOX_ENV/etc/nginx.conf

$FLOX_ENV/share/proto

Nix Expression Builds

You can write a Nix expression instead of (or in addition to) defining a manifest build.

Put

*.nix

.flox/pkgs/

File Naming

• hello.nix

  → package named

  hello

• hello/default.nix

  → package named

  hello

Common Patterns

Shell Script

{writeShellApplication, curl}:
writeShellApplication {
  name = "my-ip";
  runtimeInputs = [ curl ];
  text = ''curl icanhazip.com'';
}

Your Project

{ rustPlatform, lib }:
rustPlatform.buildRustPackage {
  pname = "my-app";
  version = "0.1.0";
  src = ../../.;
  cargoLock.lockFile = "${src}/Cargo.lock";
}

Update Version

{ hello, fetchurl }:
hello.overrideAttrs (finalAttrs: _: {
  version = "2.12.2";
  src = fetchurl {
    url = "mirror://gnu/hello/hello-${finalAttrs.version}.tar.gz";
    hash = "sha256-WpqZbcKSzCTc9BHO6H6S9qrluNE72caBm0x6nc4IGKs=";
  };
})

Apply Patches

{ hello }:
hello.overrideAttrs (oldAttrs: {
  patches = (oldAttrs.patches or []) ++ [ ./my.patch ];
})

Hash Generation

1. Use

   hash = "";

2. Run

   flox build

3. Copy hash from error message

Commands

• flox build

  - build all

• flox build .#hello

  - build specific

• git add .flox/pkgs/*

  - track files

Language-Specific Build Examples

Python Application

[build.myapp]
command = '''
  mkdir -p $out/bin $out/share/myapp

  # Copy application code
  cp -r src/* $out/share/myapp/
  cp requirements.txt $out/share/myapp/

  # Create wrapper script
  cat > $out/bin/myapp << 'EOF'
#!/usr/bin/env bash
APP_ROOT="$(dirname "$(dirname "$(readlink -f "$0")")")"
export PYTHONPATH="$APP_ROOT/share/myapp:$PYTHONPATH"
exec python3 "$APP_ROOT/share/myapp/main.py" "$@"
EOF
  chmod +x $out/bin/myapp
'''
version = "1.0.0"

Node.js Application

[build.webapp]
command = '''
  npm ci
  npm run build

  mkdir -p $out/share/webapp
  cp -r dist/* $out/share/webapp/
  cp package.json package-lock.json $out/share/webapp/

  cd $out/share/webapp && npm ci --production
'''
version = "1.0.0"

Rust Binary

[build.cli]
command = '''
  cargo build --release
  mkdir -p $out/bin
  cp target/release/mycli $out/bin/
'''
version.command = "cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version'"

Debugging Build Issues

Common Problems

Build hooks don't run:

[hook]

flox build

Package groups: Only

toplevel

Network access: Pure builds can't access network on Linux

Debugging Steps

1. Check build output:

   flox build -v

2. Inspect result:

   ls -la result-<name>/

3. Test binary:

   ./result-<name>/bin/<name>

4. Check dependencies:

   nix-store -q --references result-<name>

Related Skills

• flox-environments - Setting up development and runtime environments
• flox-publish - Publishing built packages to catalogs, understanding the dev→publish→runtime workflow
• flox-containers - Building container images