pixi

Pixi 助手

为使用 Pixi 提供专业指导。Pixi 是一款基于 conda、适用于 Python 项目的快速包管理器。

用途

帮助开发者有效使用 Pixi 管理 conda/PyPI 依赖项、在隔离环境中运行命令，以及配置多环境项目。

适用场景

• 使用 pixi.toml 或 pixi.lock 文件
• 安装或管理包
• 在 pixi 环境中运行命令或任务
• 设置开发/生产环境
• 调试 pixi 配置错误

---

快速命令参考

基本命令

# Initialize & install
pixi init [project-name]
pixi install                         # install default environment
pixi install -e dev                  # install dev environment

# Add dependencies
pixi add python=3.11 pytorch pandas  # conda packages
pixi add --pypi transformers         # PyPI packages
pixi add --feature dev pytest ruff   # to dev feature

# Run commands
pixi run python script.py            # use default env
pixi run -e dev pytest               # use dev env
pixi shell                           # interactive shell
pixi shell -e dev                    # dev shell

# Tasks
pixi task add lint "ruff check ."
pixi task list
pixi run lint

# Production
pixi run --frozen --no-install train.py

关键选项

• -e <env>：使用指定环境
• --frozen：不更新锁文件（确保可复现）
• --no-install：跳过安装
• --feature <name>：指定目标 feature

---

核心概念

工作区

包含以下内容的目录：

• pixi.toml：配置文件（提交此文件）
• pixi.lock：锁文件（提交此文件）
• .pixi/：环境缓存（不要提交）

环境

命名的依赖项集合。使用 -e 选项进行选择：

pixi run python script.py       # default
pixi run -e dev pytest           # dev
pixi run -e prod train.py        # prod

Features

可复用的依赖项组，可组合到环境中。

任务

pixi.toml 中预定义的命令。使用 pixi run <task-name> 运行。

---

命令模式

应在何时使用什么命令

目标	命令
首次设置	pixi install
添加包	pixi add <pkg>
运行单条命令	pixi run <cmd>
交互式工作	pixi shell
执行任务	pixi run <task>
生产环境	pixi run --frozen --no-install

添加依赖项

优先使用 conda（兼容性更好、速度更快）：

pixi add numpy pytorch

需要时使用 PyPI：

pixi add --pypi transformers

为什么优先使用 conda？ Pixi 会先解析 conda 依赖项，再解析 PyPI 依赖项。

---

pixi.toml 配置

项目元数据

[project]
name = "my-project"
channels = ["conda-forge", "pytorch"]  # order matters
platforms = ["linux-64", "osx-arm64"]

依赖项

[dependencies]
python = ">=3.10"
numpy = "*"
pytorch = ">=2.0,<3"

[pypi-dependencies]
transformers = "*"
my-pkg = { path = "./local", editable = true }

任务

简单任务：

[tasks]
test = "pytest tests/"

使用环境变量：

[tasks.train]
cmd = "python train.py"
env = { CUDA_VISIBLE_DEVICES = "0,1" }

使用依赖项：

[tasks]
clean = "rm -rf __pycache__"
test = { cmd = "pytest", depends-on = ["clean"] }

多行任务：

[tasks.submit]
cmd = """
python train.py \
  --config config.yaml \
  --output results/
"""

Features

[feature.dev.dependencies]
pytest = "*"
ruff = "*"

[feature.cuda.dependencies]
pytorch-cuda = "12.1"

[environments]
default = []
dev = ["dev"]
gpu = ["cuda"]
dev-gpu = ["dev", "cuda"]

激活环境

[activation.env]
CUDA_HOME = "/usr/local/cuda"
PROJECT_ROOT = "$PIXI_PROJECT_ROOT"

---

常见工作流

你的模式（susser-tod）

开发测试：

pixi run -e dev pytest ./tests

类型检查：

pixi run typecheck

性能分析：

pixi run -e dev nsys profile python train.py

---

故障排除

1. 找不到包

检查项：

1. 是否在 channels = [...] 中指定了 channel？
2. 包名是否正确？尝试：pixi search <pkg>
3. 尝试使用 PyPI：pixi add --pypi <pkg>

2. 环境未激活

❌ 错误：python script.py（直接调用 python） ✅ 正确：pixi run python script.py

4. 锁文件冲突

合并冲突后：

pixi install              # regenerate lock
# or
rm pixi.lock && pixi install

5. 未设置环境变量

[activation.env] 中的变量仅在以下情况下生效：

• pixi run <cmd>
• 在 pixi shell 中

在 pixi 外直接运行 python 时不会生效。

6. 依赖项版本冲突

使用 solve-group 隔离环境：

[environments]
default = { solve-group = "group1" }
dev = { features = ["dev"], solve-group = "group1" }  # shared
prod = { solve-group = "group2" }                     # isolated

---

最佳实践

依赖项

✅ 优先使用 Conda，需要时再用 PyPI ✅ 固定关键版本：pytorch = "2.1.*" ✅ 使用版本约束：python = ">=3.10,<3.12" ❌ 不要对同一个包混用 conda 和 PyPI

锁文件

✅ 提交 pixi.lock ✅ 在 CI/生产环境中使用 --frozen

环境

✅ 使用 features 组织依赖项 ✅ 尽可能共享 solve-groups ✅ 2–4 个环境最为理想

---

参考资料

• pixi.toml 详细架构：参见 REFERENCE.md
• 官方文档：https://pixi.sh/latest/
• pixi.toml 规范：https://pixi.sh/latest/reference/pixi_toml/

---

Pixi 实用指南。有关项目特定模式，请查看你的 CLAUDE.md。