flox-environments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flox Environments Guide

Flox 环境指南

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

在钩子中使用模块化、幂等的bash函数
绝对不要使用绝对路径。Flox环境的设计初衷就是可复现，请改用Flox提供的环境变量
我再强调一遍：绝对不要使用绝对路径，不要这么做。环境专属的运行时依赖请使用
```
$FLOX_ENV
```
变量，项目目录请使用
```
$FLOX_ENV_PROJECT
```
变量
函数命名要具有描述性（例如
```
setup_postgres()
```
）
创建交互式使用的环境时，可以考虑使用gum实现风格化输出；这一做法在CI场景下属于反模式
将持久化数据/配置存放在
```
$FLOX_ENV_CACHE
```
中
钩子执行结束后回到
```
$FLOX_ENV_PROJECT
```
目录
临时文件使用
```
mktemp
```
创建，用完立即清理
不要过度设计：例如不要添加不必要的echo语句或冗余注释；不要在
```
[hook]
```
或
```
[profile]
```
中打印不必要的信息；没有用户明确要求的情况下，不要创建辅助函数或别名

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
```
  )

支持
```
VARIABLE=value flox activate
```
模式实现运行时覆盖
绝对不要在清单中存储密钥，请使用：
- 环境变量
- 持久化密钥存储在
```
~/.config/<env_name>/
```
- 现有配置文件（例如
```
~/.aws/credentials
```
  ）

Flox Basics

Flox 基础

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)

Flox基于Nix构建，完全兼容Nix
Flox使用nixpkgs作为上游源，软件包命名通常与之一致；与nixpkgs不同的是，Flox目录包含数百万个历史包版本组合
关键路径：
- ```
.flox/env/manifest.toml
```
  : 环境定义文件
- ```
.flox/env.json
```
  : 环境元数据
- ```
$FLOX_ENV_CACHE
```
  : 持久化本地存储（执行
```
flox delete
```
  后仍会保留）
- ```
$FLOX_ENV_PROJECT
```
  : 项目根目录（.flox/文件夹所在位置）
- ```
$FLOX_ENV
```
  : 基本等价于
```
/usr
```
  路径：包含特定Flox环境可用的所有库、头文件、二进制文件、配置等内容
始终使用
```
flox init
```
创建环境
清单修改会在下次执行
```
flox activate
```
时生效（不支持热重载）

Core Commands

核心命令

bash

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

bash

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

```
[install]
```
: 带描述符的软件包列表
```
[vars]
```
: 静态变量
```
[hook]
```
: 非交互式设置脚本
```
[profile]
```
: Shell专属函数/别名
```
[services]
```
: 服务定义（参见flox-services技能）
```
[build]
```
: 可复现构建命令（参见flox-builds技能）
```
[include]
```
: 组合其他环境（参见flox-sharing技能）
```
[options]
```
: 激活模式、支持的系统

The [install] Section

[install] 配置段

Package Installation Basics

软件包安装基础

The

[install]

table specifies packages to install.

toml

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

[install]

表用于指定要安装的软件包。

toml

[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

每个条目包含：

键：安装ID（例如
```
ripgrep
```
、
```
pip
```
）- 你对该软件包的引用名称
值：软件包描述符 - 指定要安装的内容

Catalog Descriptors (Most Common)

目录描述符（最常用）

Options for packages from the Flox catalog:

toml

[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)

来自Flox目录的软件包可用选项：

toml

[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)

pkg-path（必填）

软件包在目录中的位置
可以是简单格式（
```
"ripgrep"
```
）或嵌套格式（
```
"python310Packages.pip"
```
）
支持数组格式：
```
["python310Packages", "pip"]
```

pkg-group

对兼容的软件包进行分组
未显式指定分组的软件包属于默认分组
同组软件包会一起升级以保持兼容性
使用不同分组可避免版本冲突

version

精确版本：
```
"1.2.3"
```
Semver范围：
```
"^1.2"
```
、
```
">=2.0"
```
部分版本可作为通配符：
```
"1.2"
```
= 最新的1.2.X版本

systems

限制软件包仅在特定平台可用

可选值：

"x86_64-linux"

、

"x86_64-darwin"

、

"aarch64-linux"

、

"aarch64-darwin"

省略时默认使用清单的
```
options.systems
```
配置

priority

解决软件包之间的文件冲突
默认值：5
数值越小 = 优先级越高，冲突时优先生效
对CUDA软件包至关重要（参见flox-cuda技能）

Practical Examples

实际示例

toml

undefined

toml

undefined

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"

undefined

[install] gcc.pkg-path = "gcc12" gcc.pkg-group = "stable"

undefined

Language-Specific Patterns

语言专属配置模式

Python Virtual Environments

Python 虚拟环境

venv creation pattern: Always check existence before activation:

bash

if [ ! -d "$venv" ]; then
  uv venv "$venv" --python python3
fi

虚拟环境创建模式：激活前务必先检查是否存在：

bash

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

if [ -f "$venv/bin/activate" ]; then source "$venv/bin/activate" fi


**关键模式**：
- **虚拟环境位置**：始终使用`$FLOX_ENV_CACHE/venv` - 环境重建后仍会保留
- **uv搭配虚拟环境**：使用`uv pip install --python "$venv/bin/python"`，不要用`"$venv/bin/python" -m uv`
- **缓存目录**：将`UV_CACHE_DIR`和`PIP_CACHE_DIR`设置为`$FLOX_ENV_CACHE`的子目录
- **依赖安装标记**：创建`$FLOX_ENV_CACHE/.deps_installed`标记文件避免重复安装

C/C++ Development

C/C++ 开发

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):

toml

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

软件包命名：用
```
gbenchmark
```
而非
```
benchmark
```
，Catch2使用
```
catch2_3
```
，指定版本用
```
gcc13
```
/
```
clang_18
```
系统约束：仅Linux可用的工具需要显式指定系统：
```
valgrind.systems = ["x86_64-linux", "aarch64-linux"]
```
必要分组：单独设置
```
compilers
```
、
```
build
```
、
```
debug
```
、
```
testing
```
、
```
libraries
```
分组避免冲突
libstdc++ 访问：始终包含
```
gcc-unwrapped
```
以获取C++标准库头文件/库（单独的gcc包不会暴露这些内容）：

toml

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

Node.js Development

Node.js 开发

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

包管理器：安装
```
nodejs
```
（已包含npm）；如有需要可单独添加
```
yarn
```
或
```
pnpm
```
版本锁定：LTS版本使用
```
version = "^20.0"
```
，需要可复现性时使用精确版本
全局工具模式：一次性工具使用
```
npx
```
，常用全局工具在清单中安装

Platform-Specific Patterns

平台专属配置模式

toml

undefined

toml

undefined

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"]

undefined

coreutils.pkg-path = "coreutils" coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

undefined

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

安装新软件包前先检查清单
钩子中使用
```
return
```
而非
```
exit
```
定义环境变量使用
```
${VAR:-default}
```
格式
组合环境中使用带前缀的描述性函数名
下载资源缓存到
```
$FLOX_ENV_CACHE
```
添加到服务前先使用
```
flox activate -- <command>
```
测试激活逻辑
钩子中uv/pip命令添加
```
--quiet
```
参数减少冗余输出

Editing Manifests Non-Interactively

非交互式编辑清单

bash

flox list -c > /tmp/manifest.toml

bash

flox list -c > /tmp/manifest.toml

Edit with sed/awk

flox edit -f /tmp/manifest.toml

undefined

flox edit -f /tmp/manifest.toml

undefined

Common Pitfalls

常见陷阱

Hooks Run Every Activation

每次激活都会运行钩子

Hooks run EVERY activation (keep them fast/idempotent)

钩子在每次环境激活时都会运行（请保持钩子逻辑快速且幂等）

Hook vs Profile Functions

钩子与Profile函数的区别

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

[profile]

for user-invokable commands/aliases

钩子函数在交互式Shell中对用户不可用；用户可调用的命令/别名请放在

[profile]

中

Profile Code in Layered Environments

分层环境中的Profile代码

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

[hook]

to avoid repetition

每个分层/组合的环境都会运行Profile代码；自动运行的展示逻辑请放在

[hook]

中避免重复执行

Manifest Syntax Errors

清单语法错误

Manifest syntax errors prevent ALL flox commands from working

清单语法错误会导致所有flox命令无法运行

Package Search Case Sensitivity

软件包搜索区分大小写

Package search is case-sensitive; use

flox search --all

for broader results

软件包搜索区分大小写；如需更宽泛的结果请使用

flox search --all

Troubleshooting Tips

故障排查技巧

Package Conflicts

软件包冲突

If packages conflict, use different

pkg-group

values or adjust

priority

如果软件包发生冲突，使用不同的

pkg-group

值或调整

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

如果需要
```
libstdc++
```
，从
```
gcc-unwrapped
```
包获取，不要用
```
gcc
```
包
如果用户使用Python并提到
```
uv
```
，通常不是指
```
uvicorn
```
；请确认用户需要的是哪个包

Hook Issues

钩子问题

Use
```
return
```
not
```
exit
```
in hooks
Define env vars with
```
${VAR:-default}
```
Guard FLOX_ENV_CACHE usage:
```
${FLOX_ENV_CACHE:-}
```
with fallback

钩子中使用
```
return
```
而非
```
exit
```
定义环境变量使用
```
${VAR:-default}
```
格式
使用
```
FLOX_ENV_CACHE
```
时添加兜底逻辑：
```
${FLOX_ENV_CACHE:-}
```

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.

分层是指运行时堆叠环境，激活顺序会影响最终效果。每个层在自己的子Shell中运行，在保留隔离性的同时支持工具组合。

Core Layering Commands

核心分层命令

bash

undefined

bash

undefined

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

undefined

flox activate -r prod/app -- flox activate

undefined

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:

bash

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

Debugging tools on CUDA environment:

bash

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

Temporary utilities:

bash

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

在生产环境上叠加开发工具：

bash

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

在CUDA环境上叠加调试工具：

bash

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

临时工具：

bash

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

Creating Layer-Optimized Environments

创建适配分层的环境

Design for runtime stacking with potential conflicts:

toml

[vars]

针对运行时堆叠和潜在冲突设计：

toml

[vars]

Prefix vars to avoid masking

MYAPP_PORT = "8080" MYAPP_HOST = "localhost"

[profile.common]

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

myapp_setup() { ... } myapp_debug() { ... }

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


**可分层环境的最佳实践：**
- 每个环境保持单一职责
- 预期变量/二进制文件可能被上层覆盖
- 文档说明环境提供的内容和依赖要求
- 保持钩子逻辑快速且幂等
- 使用带前缀的命名避免冲突