Flox Environments Guide

Working Style & Structure

• Use modular, idempotent bash functions in hooks
• Never, ever use absolute paths. Flox environments are designed to be reproducible. Use Flox's environment variables instead
• I REPEAT: NEVER, EVER USE ABSOLUTE PATHS. Don't do it. Use

  $FLOX_ENV

  for environment-specific runtime dependencies; use

  $FLOX_ENV_PROJECT

  for the project directory
• Name functions descriptively (e.g.,

  setup_postgres()

  )
• Consider using gum for styled output when creating environments for interactive use; this is an anti-pattern in CI
• Put persistent data/configs in

  $FLOX_ENV_CACHE

• Return to

  $FLOX_ENV_PROJECT

  at end of hooks
• Use

  mktemp

  for temp files, clean up immediately
• Do not over-engineer: e.g., do not create unnecessary echo statements or superfluous comments; do not print unnecessary information displays in

  [hook]

  or

  [profile]

  ; do not create helper functions or aliases without the user requesting these explicitly

Configuration & Secrets

• Support

  VARIABLE=value flox activate

  pattern for runtime overrides
• Never store secrets in manifest; use:
  • Environment variables

  • ~/.config/<env_name>/

    for persistent secrets
  • Existing config files (e.g.,

    ~/.aws/credentials

    )

Flox Basics

• Flox is built on Nix; fully Nix-compatible
• Flox uses nixpkgs as its upstream; packages are usually named the same; unlike nixpkgs, Flox Catalog has millions of historical package-version combinations
• Key paths:

  • .flox/env/manifest.toml

    : Environment definition

  • .flox/env.json

    : Environment metadata

  • $FLOX_ENV_CACHE

    : Persistent, local-only storage (survives

    flox delete

    )

  • $FLOX_ENV_PROJECT

    : Project root directory (where .flox/ lives)

  • $FLOX_ENV

    : basically the path to

    /usr

    : contains all the libs, includes, bins, configs, etc. available to a specific flox environment
• Always use

  flox init

  to create environments
• Manifest changes take effect on next

  flox activate

  (not live reload)

Core Commands

flox init                       # Create new env
flox search <string> [--all]    # Search for a package
flox show <pkg>                 # Show available historical versions of a package
flox install <pkg>              # Add package
flox list [-e | -c | -n | -a]   # List installed packages
flox activate                   # Enter env
flox activate -- <cmd>          # Run without subshell
flox edit                       # Edit manifest interactively

Manifest Structure

• [install]

  : Package list with descriptors

• [vars]

  : Static variables

• [hook]

  : Non-interactive setup scripts

• [profile]

  : Shell-specific functions/aliases

• [services]

  : Service definitions (see flox-services skill)

• [build]

  : Reproducible build commands (see flox-builds skill)

• [include]

  : Compose other environments (see flox-sharing skill)

• [options]

  : Activation mode, supported systems

The [install] Section

Package Installation Basics

The

[install]

table specifies packages to install.

[install]
ripgrep.pkg-path = "ripgrep"
pip.pkg-path = "python310Packages.pip"

Package Descriptors

Each entry has:

• Key: Install ID (e.g.,

  ripgrep

  ,

  pip

  ) - your reference name for the package
• Value: Package descriptor - specifies what to install

Catalog Descriptors (Most Common)

Options for packages from the Flox catalog:

[install]
example.pkg-path = "package-name"           # Required: location in catalog
example.pkg-group = "mygroup"               # Optional: group packages together
example.version = "1.2.3"                   # Optional: exact or semver range
example.systems = ["x86_64-linux"]          # Optional: limit to specific platforms
example.priority = 3                        # Optional: resolve file conflicts (lower = higher priority)

Key Options Explained:

pkg-path (required)

• Location in the package catalog
• Can be simple (

  "ripgrep"

  ) or nested (

  "python310Packages.pip"

  )
• Can use array format:

  ["python310Packages", "pip"]

pkg-group

• Groups packages that work well together
• Packages without explicit group belong to default group
• Groups upgrade together to maintain compatibility
• Use different groups to avoid version conflicts

version

• Exact:

  "1.2.3"

• Semver ranges:

  "^1.2"

  ,

  ">=2.0"

• Partial versions act as wildcards:

  "1.2"

  = latest 1.2.X

systems

• Constrains package to specific platforms
• Options:

  "x86_64-linux"

  ,

  "x86_64-darwin"

  ,

  "aarch64-linux"

  ,

  "aarch64-darwin"

• Defaults to manifest's

  options.systems

  if omitted

priority

• Resolves file conflicts between packages
• Default: 5
• Lower number = higher priority wins conflicts
• Critical for CUDA packages (see flox-cuda skill)

Practical Examples

# Platform-specific Python
[install]
python.pkg-path = "python311Full"
uv.pkg-path = "uv"
systems = ["x86_64-linux", "aarch64-linux"]  # Linux only

# Version-pinned with custom priority
[nodejs]
nodejs.pkg-path = "nodejs"
version = "^20.0"
priority = 1  # Takes precedence in conflicts

# Multiple package groups to avoid conflicts
[install]
gcc.pkg-path = "gcc12"
gcc.pkg-group = "stable"

Language-Specific Patterns

Python Virtual Environments

venv creation pattern: Always check existence before activation:

if [ ! -d "$venv" ]; then
  uv venv "$venv" --python python3
fi
# Guard activation - venv creation might not be complete
if [ -f "$venv/bin/activate" ]; then
  source "$venv/bin/activate"
fi

Key patterns:

• venv location: Always use

  $FLOX_ENV_CACHE/venv

  - survives environment rebuilds
• uv with venv: Use

  uv pip install --python "$venv/bin/python"

  NOT

  "$venv/bin/python" -m uv

• Cache dirs: Set

  UV_CACHE_DIR

  and

  PIP_CACHE_DIR

  to

  $FLOX_ENV_CACHE

  subdirs
• Dependency installation flag: Touch

  $FLOX_ENV_CACHE/.deps_installed

  to prevent reinstalls

C/C++ Development

• Package Names:

  gbenchmark

  not

  benchmark

  ,

  catch2_3

  for Catch2,

  gcc13

  /

  clang_18

  for specific versions
• System Constraints: Linux-only tools need explicit systems:

  valgrind.systems = ["x86_64-linux", "aarch64-linux"]

• Essential Groups: Separate

  compilers

  ,

  build

  ,

  debug

  ,

  testing

  ,

  libraries

  groups prevent conflicts
• libstdc++ Access: ALWAYS include

  gcc-unwrapped

  for C++ stdlib headers/libs (gcc alone doesn't expose them):

gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.priority = 5
gcc-unwrapped.pkg-group = "libraries"

Node.js Development

• Package managers: Install

  nodejs

  (includes npm); add

  yarn

  or

  pnpm

  separately if needed
• Version pinning: Use

  version = "^20.0"

  for LTS, or exact versions for reproducibility
• Global tools pattern: Use

  npx

  for one-off tools, install commonly-used globals in manifest

Platform-Specific Patterns

# Darwin-specific frameworks
IOKit.pkg-path = "darwin.apple_sdk.frameworks.IOKit"
IOKit.systems = ["x86_64-darwin", "aarch64-darwin"]

# Platform-preferred compilers
gcc.pkg-path = "gcc"
gcc.systems = ["x86_64-linux", "aarch64-linux"]
clang.pkg-path = "clang"
clang.systems = ["x86_64-darwin", "aarch64-darwin"]

# Darwin GNU compatibility layer
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Best Practices

• Check manifest before installing new packages
• Use

  return

  not

  exit

  in hooks
• Define env vars with

  ${VAR:-default}

• Use descriptive, prefixed function names in composed envs
• Cache downloads in

  $FLOX_ENV_CACHE

• Test activation with

  flox activate -- <command>

  before adding to services
• Use

  --quiet

  flag with uv/pip in hooks to reduce noise

Editing Manifests Non-Interactively

flox list -c > /tmp/manifest.toml
# Edit with sed/awk
flox edit -f /tmp/manifest.toml

Common Pitfalls

Hooks Run Every Activation

Hooks run EVERY activation (keep them fast/idempotent)

Hook vs Profile Functions

Hook functions are not available to users in the interactive shell; use

[profile]

for user-invokable commands/aliases

Profile Code in Layered Environments

Profile code runs for each layered/composed environment; keep auto-run display logic in

[hook]

to avoid repetition

Manifest Syntax Errors

Manifest syntax errors prevent ALL flox commands from working

Package Search Case Sensitivity

Package search is case-sensitive; use

flox search --all

for broader results

Troubleshooting Tips

Package Conflicts

If packages conflict, use different

pkg-group

values or adjust

priority

Tricky Dependencies

• If we need

  libstdc++

  , we get this from the

  gcc-unwrapped

  package, not from

  gcc

• If user is working with python and requests

  uv

  , they typically do not mean

  uvicorn

  ; clarify which package user wants

Hook Issues

• Use

  return

  not

  exit

  in hooks
• Define env vars with

  ${VAR:-default}

• Guard FLOX_ENV_CACHE usage:

  ${FLOX_ENV_CACHE:-}

  with fallback

Environment Layering

What is Layering?

Layering is runtime stacking of environments where activate order matters. Each layer runs in its own subshell, preserving isolation while allowing tool composition.

Core Layering Commands

# Layer debugging tools on base environment
flox activate -r team/base -- flox activate -r team/debug

# Layer multiple environments
flox activate -r team/db -- flox activate -r team/cache -- flox activate

# Layer local on remote
flox activate -r prod/app -- flox activate

When to Use Layering

• Ad hoc tool addition: Add debugging/profiling tools temporarily
• Development vs production: Layer dev tools on production environment
• Flexible composition: Mix and match environments at runtime
• Temporary utilities: Add one-time tools without modifying environment

Layering Use Cases

Development tools on production environment:

flox activate -r prod/app -- flox activate -r dev/tools

Debugging tools on CUDA environment:

flox activate -r team/cuda-base -- flox activate -r team/cuda-debug

Temporary utilities:

flox activate -r project/main -- flox activate -r utils/network

Creating Layer-Optimized Environments

Design for runtime stacking with potential conflicts:

[vars]
# Prefix vars to avoid masking
MYAPP_PORT = "8080"
MYAPP_HOST = "localhost"

[profile.common]
# Use unique, prefixed function names
myapp_setup() { ... }
myapp_debug() { ... }

[services.myapp-db]  # Prefix service names
command = "..."

Best practices for layerable environments:

• Single responsibility per environment
• Expect vars/binaries might be overridden by upper layers
• Document what the environment provides/expects
• Keep hooks fast and idempotent
• Use prefixed names to avoid collisions

Related Skills

• flox-services - Running services and background processes
• flox-builds - Building and packaging applications
• flox-publish - Publishing packages to catalogs
• flox-sharing - Environment composition and layering
• flox-containers - Containerizing environments
• flox-cuda - CUDA/GPU development environments