Pixi 是什么？#

一句话说，Pixi 是一个基于 conda 生态、同时兼容 PyPI 的项目级环境管理工具。

传统上，我们常把 Python 环境理解成一个单独的虚拟环境：先创建环境，再激活环境，再在里面安装包。Pixi 的思路稍微不同：它更强调 workspace，也就是“项目工作区”。一个 Pixi workspace 通常包含：

1
your-project/
2
├── pixi.toml 或 pyproject.toml
3
├── pixi.lock
4
└── .pixi/

其中，pixi.toml 或 pyproject.toml 描述项目需要什么依赖、支持哪些平台、有哪些任务；pixi.lock 记录精确解析出来的依赖版本；.pixi/ 则存放项目实际使用的环境。官方从 Conda/Mamba 迁移指南中也明确指出，Pixi 与 Conda/Mamba 的差异在于：Conda/Mamba 主要围绕 environment，而 Pixi 更强调 workspace；workspace 中包含 manifest、lockfile 和 .pixi 环境目录，因此更适合项目共享与协作。([Pixi][2])

这点很重要。环境不再只是你电脑上的一个“状态”，而是项目的一部分。别人拿到你的代码仓库，只要有 pixi.toml/pyproject.toml 和 pixi.lock，就能更可靠地复现你的开发环境。

为什么 Pixi 特别适合 Python？#

Python 环境管理的难点不只是“装包”，而是包之间的来源和依赖模型非常复杂。一个现代 Python 项目可能同时依赖：

1
Python 解释器
2
numpy / pandas / scipy
3
pytorch / tensorflow
4
opencv / GDAL / CUDA 相关库
5
ruff / pytest / ipython
6
纯 Python 包
7
带 C/C++/Fortran/Rust 扩展的包

如果只使用 pip，它主要面对的是 PyPI 生态。PyPI 很大、包很多，但一些带系统级二进制依赖的库并不总是好装。Pixi 的优势在于它建立在 conda 生态之上，而 conda 是跨平台、跨语言的包生态，常用于数据科学和机器学习，特点是安装预构建的二进制包；同时 Pixi 也能安装 PyPI 包。官方 Python 教程举了 GDAL 的例子：PyPI 上的 GDAL 不包含二进制 C 依赖，而 conda 包包含；另一方面，也有一些包只在 PyPI 上发布，Pixi 也可以安装它们。([Pixi][3])

换句话说，Pixi 的定位不是“替代 pip”，也不是“换皮 conda”，而是把两个世界接在一起：能从 conda-forge 装的优先从 conda-forge 装，需要 PyPI 的再从 PyPI 装。官方文档也说明，Pixi 同时建立在 conda 和 PyPI 两个生态之上，并采用 conda-first 的策略：先解析 conda 依赖，再映射到 PyPI 包，最后解析剩余 PyPI 依赖。([Pixi][4])

Pixi 相比 pip、venv、conda、poetry、uv 的核心优势#

如果只写很小的纯 Python 脚本，venv + pip 已经够用。但一旦项目变复杂，Pixi 的优势会逐渐体现出来。

官方首页给了一个简化对比：Pixi 支持安装 Python、支持多语言、支持 lockfile、内置 task runner，并支持 workspace 管理；而 pip 不负责安装 Python，也不提供环境管理和 lockfile；Poetry 偏 Python 包管理；uv 很快，也支持 Python 和 lockfile，但官方表格中 Pixi 的优势在于多语言、任务系统和 workspace 管理。([Pixi][1])

可以这样理解：

Pixi 最值得推荐的地方是：它不是只解决一个局部问题，而是把“Python 版本、依赖来源、环境复现、任务运行、多平台协作”放进同一个项目模型里。

快速上手#

安装 Pixi 很简单。Linux 和 macOS 可以使用：

1
curl -fsSL https://pixi.sh/install.sh | sh

Windows 可以使用 PowerShell：

1
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

官方文档说明，安装脚本会下载最新版本的 pixi，把二进制文件放到用户目录下的 .pixi/bin，并把它加入 PATH；安装后需要重启终端或重新加载 shell 配置。([Pixi][5])

创建一个新项目：

1
pixi init hello-world
2
cd hello-world
3
pixi add python
4
pixi run python -c 'print("Hello Pixi!")'

这套命令做了三件事：初始化 workspace、把 Python 加入项目依赖、在 Pixi 管理的环境里运行 Python。官方首页也用类似例子展示了 Pixi 的基本工作流。([Pixi][1])

如果是更标准的 Python 项目，也可以使用 pyproject.toml：

1
pixi init pixi-py --format pyproject

官方 Python 教程说明，Pixi 支持 pixi.toml 和 pyproject.toml 两种 manifest 格式；在 Python 项目中，pyproject.toml 更常见。初始化后，Pixi 会在 pyproject.toml 中加入 [tool.pixi.workspace]、[tool.pixi.pypi-dependencies] 和 [tool.pixi.tasks] 等配置。([Pixi][3])

添加 Conda 和 PyPI 依赖#

默认情况下，Pixi 会把依赖作为 conda 包添加。例如：

1
pixi add black

这会在配置文件中加入类似：

1
[tool.pixi.dependencies]
2
black = ">=25.1.0,<26"

如果某个包需要从 PyPI 安装，可以加上 --pypi：

1
pixi add rich --pypi
2
pixi add "flask[async]==3.1.0" --pypi

官方 Python 教程说明，Pixi 可以同时管理 conda 依赖和 PyPI 依赖，也支持 PyPI extras，例如 flask[async]。([Pixi][3])

这对 Python 项目很实用： 像 python、numpy、pytorch、opencv 这类更依赖二进制构建的包，可以优先交给 conda-forge；一些只在 PyPI 上发布的工具包，则可以继续从 PyPI 安装。

Pixi 会自动管理 Python 解释器#

这是 Pixi 很容易被低估的一点：它不只是管理 Python 包，也可以管理 Python 本身。

在传统流程里，你可能会先用系统包管理器安装 Python，比如 brew install python、apt install python3，再创建虚拟环境。Pixi 则可以直接把 Python 解释器作为项目依赖的一部分安装。官方文档说明，在 pyproject.toml 项目中，Pixi 会根据 requires-python 字段决定安装哪个 Python 版本，从而自动管理和引导 Python 解释器，不再需要额外依赖 brew、apt 等系统安装步骤。([Pixi][3])

例如：

1
[project]
2
requires-python = ">=3.11"

然后 Pixi 会据此为项目准备合适的 Python。对于多人协作，这比“你自己先装一个差不多的 Python”可靠得多。

pixi.lock：可复现性的关键#

如果说 pixi.toml / pyproject.toml 描述“我想要什么”，那么 pixi.lock 描述的就是“Pixi 实际解析出了什么”。

官方 lockfile 文档解释：manifest 只列出项目的直接依赖；安装环境时，包管理器会进行依赖解析，找到所有直接和间接依赖，并确保版本彼此兼容；lockfile 则记录解析出的精确包、版本和元数据。它的价值在于，其他机器可以根据这个较小的文件重建出相同环境。([Pixi][6])

Pixi 的 lockfile 文件名是 pixi.lock。官方文档指出，Pixi 会为 manifest 中列出的所有环境和平台解析依赖，并把结果记录在 lockfile 中，这能显著提高项目在不同操作系统或 CPU 架构上的可复现性；很多情况下，共享 lockfile 就能让 CI 重建本地开发环境。([Pixi][6])

所以我的建议是：应用项目应当提交 pixi.lock。这和 package-lock.json、pnpm-lock.yaml 的逻辑类似。它能让别人安装到和你一致的依赖版本，而不是“今天解析一次、明天又解析出另一个版本”。

Tasks：把常用命令写进项目#

Pixi 还有一个很实用的功能：task runner。

很多项目都有固定命令：

1
pytest
2
ruff check .
3
ruff format .
4
python scripts/train.py
5
python -m my_package

如果只靠 README 记录，时间久了很容易不一致。Pixi 可以把这些命令写成 task：

1
pixi task add test pytest
2
pixi task add lint "ruff check ."
3
pixi task add fmt "ruff format ."

之后运行：

1
pixi run test
2
pixi run lint
3
pixi run fmt

官方 tasks 文档说明，构建一个包时，通常不只是运行代码，还会涉及格式化、lint、编译、测试、benchmark 等步骤；Pixi tasks 就是为了让这些工作流更容易管理。任务之间还可以声明依赖关系，例如先 configure，再 build，再 start；如果其中一个命令失败，后续任务不会继续执行。([Pixi][7])

这点对团队协作很有价值。你不用再写“请先激活环境，然后执行某某命令”，而是直接告诉别人：

1
pixi run test

Pixi 会在正确环境里执行它。

多环境：开发、测试、生产可以分开#

很多项目会有不同依赖集合：

1
default：运行项目需要的依赖
2
dev：开发工具，比如 ruff、ipython
3
test：测试工具，比如 pytest
4
prod：生产环境最小依赖

Pixi 支持在同一个 workspace 里管理多个环境。官方 Python 教程中，Pixi 可以配合 pyproject.toml 的 dependency groups 创建多个环境，例如 default 和 test；如果要在测试环境中安装或运行，可以加 --environment test。([Pixi][3])

这比把所有东西都塞进一个环境更干净。比如 pytest、ruff、mypy 这些工具只在开发或测试时需要，不一定应该进入生产环境。Pixi 允许你把它们分到对应 feature/environment 里。

多平台：同一个项目支持 macOS、Linux、Windows#

Python 项目经常遇到跨平台问题：你在 macOS 上开发，服务器是 Linux，队友可能用 Windows。Pixi 允许在 manifest 中声明 workspace 支持的平台，例如：

1
[workspace]
2
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

官方多平台文档说明，workspace.platforms 定义 workspace 支持的平台；当声明多个平台时，Pixi 会分别决定每个平台需要安装的依赖，并把这些结果存储在 lockfile 中。它还支持针对特定平台覆盖依赖或激活脚本。([Pixi][8])

这对机器学习、数据科学和后端项目都很有用。比如你可以在 macOS 上开发，在 Linux 服务器上训练模型，而依赖配置仍然保存在同一个项目里。

pixi global：顺便管理命令行工具#

除了项目环境，Pixi 还可以管理全局工具：

1
pixi global install ipython
2
pixi global install ripgrep
3
pixi global install gh

官方文档说明，pixi global 可以把工具安装到全局位置，并把可执行入口暴露到系统 PATH，使其可以在任意目录运行；默认情况下，每个包会被隔离在自己的环境里，只暴露必要入口，因此删除某个工具时不容易破坏其他无关工具，这一点类似 pipx。([Pixi][9])

对我来说，这意味着 Pixi 不仅可以管理项目，还可以管理常用 CLI 工具。比如 ipython、ruff、jupyterlab、ripgrep、gh 都可以用 Pixi 安装，而不必污染系统 Python。

一个推荐的 Python 项目模板#

如果我现在新建一个 Python 项目，我会大致这样做：

1
pixi init my-project --format pyproject
2
cd my-project
3

4
pixi add python
5
pixi add numpy pandas
6
pixi add ruff pytest --pypi
7

8
pixi task add test pytest
9
pixi task add lint "ruff check ."
10
pixi task add fmt "ruff format ."

如果是机器学习项目，可以继续加：

1
pixi add pytorch
2
pixi add jupyterlab

日常使用：

1
pixi run python main.py
2
pixi run test
3
pixi shell

提交到 Git 时，建议提交：

1
pyproject.toml / pixi.toml
2
pixi.lock
3
src/
4
tests/

不要提交：

1
.pixi/

因为 .pixi/ 是本地生成的环境目录，别人可以通过 manifest 和 lockfile 重新创建。

我为什么推荐大家尝试 Pixi？#

Pixi 最吸引我的地方，不是某一个命令特别酷，而是它对 Python 项目的抽象更完整。

它把 Python 解释器、conda 依赖、PyPI 依赖、lockfile、任务、多环境、多平台放在同一个 workspace 模型里。对于学生、科研、机器学习、数据分析、后端开发来说，这种统一性非常实用。

简单项目里，它可以替代 venv + pip，让环境更可复现； 科学计算项目里，它能继承 conda-forge 的二进制包优势； 团队项目里，它能用 lockfile 和 task runner 减少“你电脑上怎么跑”的沟通成本； 跨平台项目里，它能把不同平台的依赖结果统一记录下来。

如果你只写一次性的脚本，Pixi 可能显得有点“重”。但只要你的项目需要长期维护、多人协作、跨机器运行，或者涉及数据科学/机器学习依赖，我会非常推荐你尝试 Pixi。它让我感觉 Python 环境管理终于更接近现代前端里的 pnpm / package-lock / workspace 工作流：环境不再是混乱的本地状态，而是项目本身的一部分。

管理工作区 (workspace)##

• pixi init - 在当前目录创建一个新的 Pixi 清单文件 (manifest)
• pixi add - 向清单文件添加一个依赖项 (dependency)
• pixi remove - 从清单文件移除一个依赖项
• pixi update - 更新清单文件中的依赖项
• pixi upgrade - 将清单文件中的依赖项升级到最新版本，即使你把它们固定 (pin) 在某个特定版本上
• pixi lock - 为清单文件创建或更新锁文件 (lockfile)
• pixi info -显示工作区信息
• pixi run - 运行清单文件中定义的任务 (task)，或在当前环境中运行任意命令
• pixi shell - 在当前环境中启动一个 shell
• pixi list - 列出当前环境中的所有依赖项
• pixi tree - 显示当前环境中的依赖树 (dependency tree)
• pixi clean - 从你的机器上移除该环境

管理全局安装 (global installations)##

Pixi 可以在全局环境 (global environments) 中管理工具的全局安装。它会把这些环境安装到一个集中位置，因此你可以在任意位置使用它们。

• pixi global install - 在全局空间 (global space) 中将一个包安装到它自己的环境里
• pixi global uninstall - 从全局空间卸载一个环境
• pixi global add - 向一个已存在的全局环境添加一个包
• pixi global sync - 将全局已安装的环境与全局清单文件同步，该清单描述了你想安装的所有环境
• pixi global edit - 编辑全局清单文件
• pixi global update - 更新全局环境
• pixi global list - 列出所有全局环境

更多信息： Global Tools

运行一次性命令 (one-off commands)##

Pixi 可以在特定环境中运行一次性命令。

• pixi exec - 在临时环境 (temporary environment) 中运行一条命令
• pixi exec --spec - 在临时环境中运行一条命令，并使用指定的规格 (specification)

例如：

1
> pixi exec python -VV
2
Python 3.13.5 | packaged by conda-forge | (main, Jun 16 2025, 08:24:05) [Clang 18.1.8 ]
3
> pixi exec --spec "python=3.12" python -VV
4
Python 3.12.11 | packaged by conda-forge | (main, Jun  4 2025, 14:38:53) [Clang 18.1.8 ]

多环境 (Multiple Environments)##

Pixi 工作区允许你管理多个环境 (environment)。一个环境由一个或多个特性 (feature) 构建而成。

• pixi add --feature - 向某个特性添加一个包
• pixi task add --feature - 向某个特定特性添加一个任务
• pixi workspace environment add - 向工作区添加一个环境
• pixi run --environment - 在指定环境中运行一条命令
• pixi shell --environment - 激活 (activate) 指定环境
• pixi list --environment - 列出指定环境中的依赖项

更多信息： Multiple Environments

任务 (Tasks)##

Pixi 内置了任务运行器 (task runner)，可以运行跨平台任务 (cross-platform tasks)。任务既可以是预定义的任务，也可以是任意普通可执行文件 (executable)。

• pixi run - 运行一个任务或命令
• pixi task add - 向清单文件添加一个新任务

任务也可以依赖其他任务。下面是一个更复杂的任务用例示例：

1
[tasks]
2
build = "make build"
3
# using the toml table view
4
[tasks.test]
5
cmd = "pytest"
6
depends-on = ["build"]

更多信息： Tasks

多平台支持 (Multi platform support)##

Pixi 开箱即用地支持多种平台。你可以指定工作区支持哪些平台，Pixi 会确保依赖项与这些平台兼容。

• pixi add --platform - 只把某个包添加到指定平台
• pixi workspace platform add - 向工作区添加你希望支持的平台

更多信息： Multi platform support

实用工具 (Utilities)##

Pixi 自带了一组实用工具，帮助你调试或管理配置。

• pixi info - 显示当前工作区以及全局配置的信息
• pixi config - 显示或编辑 Pixi 配置 (configuration)
• pixi tree - 显示当前环境中的依赖树
• pixi list - 列出当前环境中的所有依赖项
• pixi clean - 从你的机器上移除工作区环境
• pixi help - 显示 Pixi 命令的帮助信息
• pixi help <subcommand> - 显示某个特定 Pixi 命令的帮助信息
• pixi auth - 管理 conda 通道 (channel) 的认证 (authentication)
• pixi search - 在已配置的通道中搜索包
• pixi completion - 为 Pixi 命令生成 shell 自动补全脚本 (completion scripts)

进一步探索 (Going further)##

Pixi 还有更多能力等待你挖掘。请查看左侧边栏中的主题来了解更多内容。

别忘了加入我们的 Discord ，和 Pixi 爱好者社区一起交流！

问题现象#

在 VS Code 中设置 Python 解释器为 Pixi 环境（启用 Pixi Code 扩展）从而自动激活环境时，打开终端会出现：

1
bash: __vsc_prompt_cmd_original: command not found

原因分析#

问题涉及三个组件的交互：

1
VS Code Shell 集成        Python 扩展             Pixi
2
    │                        │                    │
3
    │ 定义 __vsc_* 函数       │ 检测到 pixi 环境    │
4
    │ 写入 PROMPT_COMMAND    │                    │
5
    │                        │                    │
6
    │                        │── pixi shell ──────│→ 启动 bash 子进程
7
    │                        │                    │
8
    │                        │   子进程继承了 PROMPT_COMMAND
9
    │                        │   但没有继承 __vsc_* 函数
10
    │                        │                    │
11
    │                        │   bash 执行 PROMPT_COMMAND
12
    │                        │   → 找不到 __vsc_prompt_cmd_original
13
    │                        │   → 报错！

修复步骤#

共需修改 2 个文件。

1
# Fix: clean up VS Code shell integration references in sub-shells
2
# (e.g., pixi shell) where the functions are not inherited.
3
if [[ "$PROMPT_COMMAND" == *"__vsc_prompt_cmd_original"* ]] && ! type -t __vsc_prompt_cmd_original &>/dev/null; then
4
    unset PROMPT_COMMAND
5
fi

1
if [ -x ~/.pixi/bin/pixi ]; then
2
    # 启用 pixi 命令自动补全
3
    eval "$("$HOME/.pixi/bin/pixi" completion --shell bash)"
4

5
    # 如果当前目录或其父目录里有 pixi.toml，激活 pixi 环境
6
    if [[ -z "${PIXI_IN_SHELL:-}" ]]; then
7
        _dir="$PWD"
8
        while :; do
9
            if [[ -f "$_dir/pixi.toml" ]]; then
10
                eval "$("$HOME/.pixi/bin/pixi" shell-hook --manifest-path "$_dir/pixi.toml")"
11
                break
12
            fi
13
            [[ "$_dir" == "/" ]] && break
14
            _dir="$(dirname "$_dir")"
15
        done
16
        unset _dir
17
    fi
18
fi

1
{
2
    // Disable Python extension's automatic environment activation in terminal.
3
    // The pixi environment is already auto-activated via ~/.bashrc using shell-hook,
4
    // which avoids spawning a sub-shell and preserves VS Code's shell integration.
5
    "python.terminal.activateEnvironment": false
6
}

三层防护总结#

为什么不能用 export -f 导出函数？#

一个直觉的想法是：在 ~/.bashrc 中用 export -f __vsc_prompt_cmd_original 导出函数， 让子进程继承。但这条路走不通，有两个硬性障碍。

1
① shellIntegration-bash.sh 开始执行
2
② . ~/.bashrc                               ← .bashrc 在这里运行
3
③ 定义 __vsc_prompt_cmd_original 等函数       ← 函数此时还不存在！
4
④ PROMPT_COMMAND=__vsc_prompt_cmd_original

1
# 第 ② 步：先执行 .bashrc
2
if [ "$VSCODE_INJECTION" == "1" ]; then
3
    if [ -z "$VSCODE_SHELL_LOGIN" ]; then
4
        if [ -r ~/.bashrc ]; then
5
            . ~/.bashrc          # ← .bashrc 在此执行
6
        fi
7
    fi
8
fi
9

10
# ... 中间定义了大量 __vsc_* 函数 ...
11

12
# 第 ③ 步：函数在 .bashrc 之后才定义
13
__vsc_prompt_cmd_original() {
14
    __vsc_status="$?"
15
    builtin local cmd
16
    __vsc_restore_exit_code "${__vsc_status}"
17
    for cmd in "${__vsc_original_prompt_command[@]}"; do
18
        eval "${cmd:-}"
19
    done
20
    __vsc_precmd
21
}
22

23
# 第 ④ 步：设置 PROMPT_COMMAND
24
__vsc_original_prompt_command=${PROMPT_COMMAND:-}
25
if [[ -n "${__vsc_original_prompt_command:-}" ... ]]; then
26
    PROMPT_COMMAND=__vsc_prompt_cmd_original
27
fi

1
__vsc_prompt_cmd_original
2
  ├── __vsc_restore_exit_code
3
  ├── __vsc_precmd
4
  │     ├── __vsc_command_complete
5
  │     ├── __vsc_update_cwd
6
  │     │     └── __vsc_escape_value / __vsc_escape_value_fast
7
  │     ├── __vsc_report_prompt
8
  │     ├── __vsc_update_prompt
9
  │     │     ├── __vsc_prompt_start
10
  │     │     ├── __vsc_prompt_end
11
  │     │     ├── __vsc_continuation_start
12
  │     │     └── __vsc_continuation_end
13
  │     └── __vsc_update_env
14
  │           └── __updateEnvCache / __updateEnvCacheAA
15
  └── 变量: __vsc_status, __vsc_nonce, __vsc_original_prompt_command,
16
            __vsc_in_command_execution, __vsc_current_command,
17
            __vsc_is_windows, __vsc_history_verify, __vsc_first_prompt, ...

验证#

修改完成后重新打开 VS Code 终端，应该看到：

• (nodebb) 前缀正常显示（pixi 环境已激活）
• 没有 __vsc_prompt_cmd_original: command not found 错误
• 终端行号旁的命令成功/失败图标正常工作（VS Code 集成保留）