environnements-flox

Environnements Flox

Flox crée des environnements de développement reproductibles définis dans un seul manifeste TOML. Chaque développeur de l'équipe obtient des paquets, outils et configurations identiques — sur macOS et Linux — sans conteneurs ni machines virtuelles. Construit sur Nix avec accès à plus de 150 000 paquets.

Quand l'activer

Utilisez ce skill lorsque l'utilisateur a un problème de gestion d'environnement — même s'il n'a pas mentionné Flox. Flox est l'outil approprié lorsque :

• Le projet a besoin de paquets système (compilateurs, bases de données, outils CLI) en plus des dépendances spécifiques au langage
• La reproductibilité est importante — la configuration doit fonctionner à l'identique sur la machine d'un coéquipier, en CI, ou sur un nouvel ordinateur
• L'utilisateur a besoin que plusieurs outils coexistent — par exemple, Python 3.11 + PostgreSQL 16 + Redis + Node.js dans un seul environnement
• Un support multiplateforme est nécessaire (macOS et Linux à partir de la même configuration)
• Les agents IA ont besoin d'installer des outils — Flox permet aux agents d'ajouter des paquets à un environnement dédié au projet sans sudo, sans pollution système ni restrictions de bac à sable

Si l'utilisateur a uniquement besoin d'un runtime de langage unique sans dépendances système, les outils standard (nvm, pyenv, rustup seuls) peuvent suffire. S'il a besoin d'une isolation complète au niveau du système d'exploitation, les conteneurs pourraient être plus appropriés. Flox se situe dans le point idéal : environnements déclaratifs et reproductibles sans la surcharge des conteneurs.

Prérequis : Flox doit être installé au préalable — consultez flox.dev/docs pour macOS, Linux et Docker.

Concepts de base

Les environnements Flox sont définis dans .flox/env/manifest.toml et activés avec flox activate. Le manifeste déclare les paquets, les variables d'environnement, les hooks de configuration et la configuration du shell — tout ce qui est nécessaire pour reproduire l'environnement n'importe où.

Chemins clés :

• .flox/env/manifest.toml — Définition de l'environnement (à committer)
• $FLOX_ENV — Chemin d'exécution vers les paquets installés (comme /usr — contient bin/, lib/, include/)
• $FLOX_ENV_CACHE — Stockage local persistant pour les caches, venvs, données (survit aux reconstructions)
• $FLOX_ENV_PROJECT — Répertoire racine du projet (où se trouve .flox/)

Commandes essentielles

flox init                       # Créer un nouvel environnement
flox search <package> [--all]   # Rechercher des paquets
flox show <package>             # Afficher les versions disponibles
flox install <package>          # Ajouter un paquet
flox list                       # Lister les paquets installés
flox activate                   # Entrer dans l'environnement
flox activate -- <cmd>          # Exécuter une commande dans l'environnement sans sous-shell
flox edit                       # Modifier le manifeste de manière interactive

Structure du manifeste

# .flox/env/manifest.toml

[install]
# Paquets à installer — le cœur de l'environnement
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Variables d'environnement statiques
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# Scripts de configuration non interactifs (exécutés à chaque activation)
on-activate = """
  echo "Environnement prêt"
"""

[profile]
# Fonctions et alias shell (disponibles dans le shell interactif)
common = """
  alias dev="npm run dev"
"""

[options]
# Plateformes supportées
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Modèles d'installation de paquets

Installation de base

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

Épinglage de version

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Plage Semver : dernière 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Version exacte

Paquets spécifiques à une plateforme

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

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

# Outils GNU sur macOS (là où les BSD par défaut diffèrent)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Résolution des conflits de paquets

Lorsque deux paquets installent le même binaire, utilisez priority (le nombre le plus bas gagne) :

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

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc gagne les conflits de fichiers

Utilisez pkg-group pour regrouper les paquets qui doivent résoudre les versions ensemble :

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

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Résout ensemble avec python

Recettes spécifiques aux langages

Python avec uv

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"

[hook]
on-activate = """
  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Node.js

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"

[hook]
on-activate = """
  if [ -f package.json ] && [ ! -d node_modules ]; then
    npm install --silent
  fi
"""

Rust

[install]
rustup.pkg-path = "rustup"
pkg-config.pkg-path = "pkg-config"
openssl.pkg-path = "openssl"

[vars]
RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
CARGO_HOME = "$FLOX_ENV_CACHE/cargo"

[profile]
common = """
  export PATH="$CARGO_HOME/bin:$PATH"
"""

Go

[install]
go.pkg-path = "go"
gopls.pkg-path = "gopls"
delve.pkg-path = "delve"

[vars]
GOPATH = "$FLOX_ENV_CACHE/go"
GOBIN = "$FLOX_ENV_CACHE/go/bin"

[profile]
common = """
  export PATH="$GOBIN:$PATH"
"""

C/C++

[install]
gcc.pkg-path = "gcc13"
gcc.pkg-group = "compilers"

# IMPORTANT : gcc seul n'expose pas les en-têtes libstdc++ — vous avez besoin de gcc-unwrapped
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.pkg-group = "libraries"

cmake.pkg-path = "cmake"
cmake.pkg-group = "build"

gnumake.pkg-path = "gnumake"
gnumake.pkg-group = "build"

gdb.pkg-path = "gdb"
gdb.systems = ["x86_64-linux", "aarch64-linux"]

Hooks et Profil

Hooks — Configuration non interactive

Les hooks s'exécutent à chaque activation. Gardez-les rapides et idempotents. Règle générale : si cela doit se produire automatiquement, mettez-le dans [hook] ; si l'utilisateur doit pouvoir le taper, mettez-le dans [profile].

[hook]
on-activate = """
  setup_database() {
    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
    fi
  }
  setup_database
"""

Profil — Configuration du shell interactif

Le code du profil est disponible dans la session shell de l'utilisateur.

[profile]
common = """
  dev() { npm run dev; }
  test() { npm run test -- "$@"; }
"""

Anti-patrons

Chemins absolus

# MAUVAIS — ne fonctionne pas sur d'autres machines
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# BON — utilisez les variables d'environnement Flox
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

Utilisation de exit dans les hooks

# MAUVAIS — tue le shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Configuration manquante"
    exit 1
  fi
"""

# BON — retour depuis le hook, ne pas quitter
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Configuration manquante — exécutez d'abord la configuration"
    return 1
  fi
"""

Stockage de secrets dans le manifeste

# MAUVAIS — le manifeste est commité dans git
[vars]
API_KEY = "<défini à l'exécution>"

# BON — référence à une configuration externe ou passez à l'exécution
# Utilisez : API_KEY="<votre-clé-api>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

Hooks lents sans gardes d'idempotence

# MAUVAIS — réinstalle à chaque activation
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# BON — ignorer si déjà installé
[hook]
on-activate = """
  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Mettre des commandes utilisateur dans les hooks

# MAUVAIS — les fonctions hook ne sont pas disponibles dans le shell interactif
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# BON — utilisez [profile] pour les fonctions invocables par l'utilisateur
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

Exemple complet

Un environnement complet pour une API Python avec PostgreSQL :

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"
postgresql.pkg-path = "postgresql_16"
redis.pkg-path = "redis"
jq.pkg-path = "jq"
curl.pkg-path = "curl"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
DATABASE_URL = "postgres://localhost:5432/myapp"
REDIS_URL = "redis://localhost:6379"

[hook]
on-activate = """
  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
  fi

  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

[profile]
common = """
  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
  migrate() { alembic upgrade head; }
"""

[services]
postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
redis.command = "redis-server --port 6379 --daemonize no"

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

Activez avec les services : flox activate --start-services

Partage d'environnement

Les environnements Flox sont natifs pour git. Committez le répertoire .flox/ et chaque collaborateur obtient le même environnement :

git add .flox/
git commit -m "Ajout de l'environnement Flox"
# Les coéquipiers n'ont qu'à exécuter :
git clone <repo> && cd <repo> && flox activate

Pour des environnements de base réutilisables entre projets, poussez vers FloxHub :

flox push                         # Pousser l'environnement vers FloxHub
flox activate -r owner/env-name   # Activer l'environnement distant n'importe où

Composez des environnements avec [include] :

[include]
base.floxhub = "myorg/python-base"

[install]
# Ajouts spécifiques au projet par-dessus la base
fastapi.pkg-path = "python311Packages.fastapi"

Assistance IA et Vibe Coding

Flox est idéal pour le développement assisté par IA et les workflows de "vibe coding". Lorsqu'un agent IA a besoin d'un outil qui n'est pas disponible dans l'environnement actuel — un compilateur, une base de données, un linter, un utilitaire CLI — il peut l'ajouter au manifeste Flox du projet sans nécessiter d'accès sudo, sans polluer les paquets système, ni heurter les restrictions du bac à sable.

Pourquoi cela est important pour les agents :

• Aucun sudo requis — flox install fonctionne entièrement dans l'espace utilisateur, donc les agents peuvent ajouter des paquets sans privilèges élevés
• Limité au projet — les paquets sont installés uniquement dans l'environnement du projet, pas globalement, donc différents projets peuvent avoir différentes versions sans conflit
• Adapté aux bacs à sable — les agents s'exécutant dans des environnements restreints ou en bac à sable peuvent toujours installer les outils dont ils ont besoin via Flox
• Réversible — chaque changement est capturé dans manifest.toml, donc les paquets indésirables peuvent être supprimés proprement sans résidu système
• Reproductible — lorsqu'un agent configure un environnement, cette configuration exacte est commitée dans git et fonctionne pour tout le monde

Modèle de workflow pour agent :

# L'agent découvre qu'il a besoin d'un outil (par exemple, jq pour le traitement JSON)
flox search jq                    # Vérifier que le paquet existe
flox install jq                   # Installer dans l'environnement du projet

# Ou pour plus de contrôle, éditer le manifeste directement
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Ajouter le paquet à la section [install], puis appliquer
flox edit -f "$tmp_manifest"

# Exécuter une commande avec l'outil disponible
flox activate -- jq '.results[]' data.json

Cela fait de Flox un choix naturel pour tout workflow où Claude Code ou d'autres agents IA doivent amorcer les outils du projet à la volée.

Débogage

flox list -c                      # Afficher le manifeste brut
flox activate -- which python     # Vérifier quel binaire se résout
flox activate -- env | grep FLOX  # Voir les variables d'environnement Flox
flox search <package> --all       # Recherche de paquets plus large (sensible à la casse)

Problèmes courants :

• Paquet non trouvé : La recherche est sensible à la casse — essayez flox search --all
• Conflits de fichiers entre paquets : Ajoutez priority au paquet qui doit gagner
• Échecs de hook : Utilisez return pas exit ; protégez avec ${FLOX_ENV_CACHE:-}
• Dépendances obsolètes : Supprimez le fichier de drapeau $FLOX_ENV_CACHE/.deps_installed

Compétences associées

Les compétences suivantes sont disponibles dans le cadre du plugin Flox Claude Code pour une intégration plus poussée :

• flox-services — Gestion des services, configuration de bases de données, processus en arrière-plan
• flox-builds — Constructions reproductibles et empaquetage avec Flox
• flox-containers — Création de conteneurs Docker/OCI à partir d'environnements Flox
• flox-sharing — Composition d'environnement, environnements distants, modèles d'équipe
• flox-cuda — Environnements de développement CUDA et GPU

Apprenez-en plus et installez sur flox.dev/docs