Flox Environments

Flox creates reproducible development environments defined in a single TOML manifest. Every developer on the team gets identical packages, tools, and configuration — across macOS and Linux — without containers or VMs. Built on Nix with access to over 150,000 packages.

When to Activate

Use this skill when the user has an environment management problem — even if they haven't mentioned Flox. Flox is the right tool when:

• The project needs system-level packages (compilers, databases, CLI tools) alongside language-specific dependencies
• Reproducibility matters — the setup should work identically on a teammate's machine, in CI, or on a fresh laptop
• The user needs multiple tools to coexist — e.g., Python 3.11 + PostgreSQL 16 + Redis + Node.js in one environment
• Cross-platform support is needed (macOS and Linux from the same config)
• AI agents need to install tools — Flox lets agents add packages to a project-scoped environment without sudo, system pollution, or sandbox restrictions

If the user just needs a single language runtime with no system dependencies, standard tooling (nvm, pyenv, rustup alone) may suffice. If they need full OS-level isolation, containers might be more appropriate. Flox sits in the sweet spot: declarative, reproducible environments without container overhead.

Prerequisite: Flox must be installed first — see flox.dev/docs for macOS, Linux, and Docker.

Core Concepts

Flox environments are defined in .flox/env/manifest.toml and activated with flox activate. The manifest declares packages, environment variables, setup hooks, and shell configuration — everything needed to reproduce the environment anywhere.

Key paths:

• .flox/env/manifest.toml — Environment definition (commit this)
• $FLOX_ENV — Runtime path to installed packages (like /usr — contains bin/, lib/, include/)
• $FLOX_ENV_CACHE — Persistent local storage for caches, venvs, data (survives rebuilds)
• $FLOX_ENV_PROJECT — Project root directory (where .flox/ lives)

Essential Commands

flox init                       # Create new environment
flox search <package> [--all]   # Search for packages
flox show <package>             # Show available versions
flox install <package>          # Add a package
flox list                       # List installed packages
flox activate                   # Enter environment
flox activate -- <cmd>          # Run a command in the environment without a subshell
flox edit                       # Edit manifest interactively

Manifest Structure

# .flox/env/manifest.toml

[install]
# Packages to install — the core of the environment
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Static environment variables
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# Non-interactive setup scripts (run every activation)
on-activate = """
  echo "Environment ready"
"""

[profile]
# Shell functions and aliases (available in interactive shell)
common = """
  alias dev="npm run dev"
"""

[options]
# Supported platforms
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Package Installation Patterns

Basic Installation

[install]
nodejs.pkg-path = "nodejs"
python.pkg-path = "python311"
rustup.pkg-path = "rustup"

Version Pinning

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver range: latest 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Exact version

Platform-Specific Packages

[install]
# Linux-only tools
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

# macOS frameworks
Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
Security.systems = ["x86_64-darwin", "aarch64-darwin"]

# GNU tools on macOS (where BSD defaults differ)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Resolving Package Conflicts

When two packages install the same binary, use priority (lower number wins):

[install]
gcc.pkg-path = "gcc12"
gcc.priority = 3

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc wins file conflicts

Use pkg-group to group packages that should resolve versions together:

[install]
python.pkg-path = "python311"
python.pkg-group = "python-stack"

pip.pkg-path = "python311Packages.pip"

…