pixi import 命令完全指南:将 conda-env 与 pypi-txt 环境文件导入 Pixi 工作区
pixi import 命令完全指南:将 conda-env 与 pypi-txt 环境文件导入 Pixi 工作区
pixi import 是 Pixi(用 Rust 编写、基于 Conda 生态的跨平台系统级包管理器)提供的环境导入命令,用于把现成的 environment.yml(conda 生态)或 requirements.txt(PyPI 生态)环境定义文件导入到已存在的 Pixi 工作区(workspace)清单中,自动生成对应的 feature、environment 与依赖声明。读完本文,你将掌握 pixi import 的全部参数语义、两种导入格式的转换规则、与现有 feature/environment 合并的技巧,以及用 pixi init --import 一步完成工作区初始化的实战方案。
命令概览与适用场景
在已有的 Pixi 工作区中,通过一条命令即可把外部环境定义文件接入清单,省去手工抄写依赖的繁琐过程:
pixi import [OPTIONS] <FILE>
其中 <FILE> 为要导入工作区的文件,必填。该命令的核心入口实现在 crates/pixi_cli/src/import.rs,并在 crates/pixi_cli/src/lib.rs 中注册为顶层子命令。导入完成后,命令会打印 ✔ Imported to <manifest路径> 形式的成功提示。
pixi import 的典型使用场景包括:
- 从旧 conda 项目迁移:把已有的
environment.yml一键转成 Pixi 清单结构; - 复用 PyPI 生态的
requirements.txt:把 pip 风格的需求文件导入为pypi-dependencies; - 合并多个环境文件:通过
--feature/--environment把不同文件的内容并进同一环境。
导入格式与自动探测机制
目前支持两种导入文件格式,由源码中的 ImportFileFormat 枚举定义(见 crates/pixi_cli/src/import.rs):
conda-env:conda 生态的环境文件(通常叫environment.yml),遵循 conda 官方文档中手工创建环境文件的语法;pypi-txt:PyPI 生态的需求文件,遵循 pip 官方文档中的 requirements 文件格式规范。
若不给 --format,import 会依次尝试每种格式,直到某一种解析成功;如果全部失败,则报错。这一点在命令行文档的 Description 与源码的 execute 函数中均有体现(crates/pixi_cli/src/import.rs),错误信息提示用户可通过显式传入 format 参数查看该格式的具体报错:
Tried all formats for input file, but none were successful. Pass a
formatargument to see the specific error for that format.
格式参数本身是大小写不敏感的(源码中 #[arg(long, ignore_case = true)]),例如 --format=conda-env 与 --format=CondaEnv 等价。
命令行参数详解
核心参数
<FILE>:要导入工作区的文件路径,必填(required: true)。--format <FORMAT>:指定文件解释格式,取值为conda-env或pypi-txt。不提供时按上文自动探测。--platform (-p) <PLATFORM>:为导入的环境指定平台。可接受工作区平台名;也可接受裸的 conda subdir(如linux-64)。尚未声明过的名称会自动作为 subdir 平台添加。该参数可多次提供。--environment (-e) <NEW_ENVIRONMENT>:为创建的环境命名。如果不提供--feature,导入内容会被直接内联(inline)写到该环境上,而不是放进独立 feature。--feature (-f) <NEW_FEATURE>:为创建的 feature 命名。该 feature 会加入同名的环境,除非同时给了--environment。
feature 与 environment 的命名规则可以从源码 get_feature_and_environment(crates/pixi_cli/src/import.rs)中精确还原:
- 环境名取值优先级:显式
--environment>--feature(同名复用)> 文件自带name字段(仅conda-env格式有)> 报错MissingEnvironmentName; - feature 名:给了
--feature就用它;否则按"环境名"推导出同名 feature。对于pypi-txt格式,必须提供--feature或--environment(或两者都给),因为需求文件没有name字段可兜底。
配置选项(Config Options)
这些选项继承自 Pixi 全局配置体系(源码中通过 #<a href="https://link.gitcode.com/i/37cbc22916d0a3ee199f49c61309acc6" target="_blank">clap(flatten)] pub config: ConfigCli 展开,见 [crates/pixi_cli/src/import.rs),用于控制网络、链接与认证行为:
--auth-file <AUTH_FILE>:指向包含认证令牌的文件。--concurrent-downloads <CONCURRENT_DOWNLOADS>:最大并发网络请求数,默认50。--concurrent-solves <CONCURRENT_SOLVES>:最大并发 solve 数,默认为 CPU 核数。--pinning-strategy <PINNING_STRATEGY>:设置固定(pinning)策略,可选值:semver、minor、major、latest-up、exact-version、no-pin。--pypi-keyring-provider <PYPI_KEYRING_PROVIDER>:是否用系统 keyring 查询 PyPI 凭据,可选值:disabled、subprocess。--run-post-link-scripts:运行 post-link 脚本(不安全,需谨慎)。--no-symbolic-links:安装期间禁止符号链接(对应环境变量PIXI_NO_SYMBOLIC_LINKS)。--no-hard-links:安装期间禁止硬链接(对应环境变量PIXI_NO_HARD_LINKS)。--no-ref-links:安装期间禁止 ref 链接(copy-on-write,对应环境变量PIXI_NO_REF_LINKS)。--tls-no-verify:不校验服务器 TLS 证书。--offline=<OFFLINE>:离线运行,仅使用缓存数据,缓存缺失即失败。可传--offline=false覆盖配置文件中的offline设置。可取值:y/yes/t/true/on/1或n/no/f/false/off/0;对应环境变量PIXI_OFFLINE。--tls-root-certs <TLS_ROOT_CERTS>:指定使用的 TLS 根证书:webpki(内置 Mozilla 根证书)或system(系统证书库);对应环境变量PIXI_TLS_ROOT_CERTS。--use-environment-activation-cache:使用环境激活缓存(实验性功能)。--no-config:不读取系统级或用户级配置文件,但项目本地的<project>/.pixi/config.toml仍会加载;默认false;对应环境变量PIXI_NO_CONFIG。--config-file <PATH>:从指定文件加载配置,替代系统级与用户级路径的搜索;项目本地<project>/.pixi/config.toml仍会合并到其上;对应环境变量PIXI_CONFIG_FILE。
全局选项(Global Options)
--manifest-path (-m) <MANIFEST_PATH>:指向pixi.toml、pyproject.toml或工作区目录的路径。--workspace (-w) <WORKSPACE>:工作区名称。
工作区定位逻辑在源码中通过 WorkspaceLocator::for_cli() 完成(crates/pixi_cli/src/import.rs),导入前还会调用 sanity_check_workspace 对工作区做一致性检查。
导入 conda-env 格式:environment.yml
基本导入:利用文件自带 name
假设要导入的环境定义如下(典型 conda 环境文件,同时包含 conda 依赖与 pip 子依赖):
name: simple-env
channels: ["conda-forge"]
dependencies:
- python
- pip:
- httpx
执行:
pixi import --format=conda-env environment.yml
由于文件带 name: simple-env,命令会创建同名 feature(若已存在则复用之),并创建包含该 feature 且设置了 no-default-feature 的环境。导入后的 pixi.toml 如下:
[feature.simple-env]
channels = ["conda-forge"]
[feature.simple-env.dependencies]
python = "*"
[feature.simple-env.pypi-dependencies]
httpx = "*"
[environments]
simple-env = { features = ["simple-env"], no-default-feature = true }
可以看到转换规则非常清晰:conda 依赖进 dependencies,pip: 子块进 pypi-dependencies,channels 进 feature 的 channels 表。转换逻辑由 crates/pixi_utils/src/conda_environment_file.rs 中的 CondaEnvFile::to_manifest 与 parse_dependencies 实现:conda 依赖用宽松模式(ParseStrictness::Lenient)解析为 MatchSpec,pip 依赖按 PEP 508 规范解析为 pep508_rs::Requirement。
导入完成后,就可以为这个环境定义任务(task)、用 pixi run 在其中运行命令、或用 pixi shell 进入该环境交互使用。
导入到现有 feature/environment(环境合并)
对于没有 name 字段的文件,或想覆盖默认行为时,可显式指定 --feature 与 --environment。这也允许导入进已存在的 feature 与环境(包括 default feature/environment)。
例如有另一个环境文件:
channels: ["conda-forge"]
dependencies:
- numpy
执行:
pixi import --format=conda-env --feature=numpy --environment=simple-env env2.yml
会把内容导入到名为 numpy 的新 feature,并把该 feature 并入已存在的 simple-env 环境(等效于把两份环境文件合并):
[feature.simple-env]
channels = ["conda-forge"]
[feature.simple-env.dependencies]
python = "*"
[feature.simple-env.pypi-dependencies]
httpx = "*"
[feature.numpy]
channels = ["conda-forge"]
[feature.numpy.dependencies]
numpy = "*"
[environments]
simple-env = { features = ["simple-env", "numpy"], no-default-feature = true }
这一合并行为在源码 import 函数中有明确的对应逻辑(crates/pixi_cli/src/import.rs):若目标环境不存在,则创建带该 feature 且 no-default-feature=true 的环境;若环境已存在,则把 feature 追加进环境的 features 列表(若尚未包含)。
指定平台:--platform
通过 --platform 可限定导入 feature 的平台范围。例如:
pixi import --format=conda-env --feature=unix --platform=linux-64 --platform=osx-arm64 environment.yml
生成如下清单:
[feature.unix]
platforms = ["linux-64", "osx-arm64"]
channels = ["conda-forge"]
[feature.unix.target.linux-64.dependencies]
python = "*"
[feature.unix.target.osx-arm64.dependencies]
python = "*"
[environments]
unix = { features = ["unix"], no-default-feature = true }
平台解析在源码中通过 resolve_platforms 完成(crates/pixi_cli/src/import.rs):import 没有(也不读取)目标工作区的平台表,因此每个平台名都必须能解析为 conda subdir;用户日后可用 workspace platform edit 对生成的条目重命名。--platform 也可与 --environment 组合使用。
导入 pypi-txt 格式:requirements.txt
pypi-txt 格式面向 PyPI 生态的 requirements 文件。假设文件内容为:
cowpy
array-api-extra>=0.8
执行(pypi-txt 格式必须显式给 --feature 或 --environment,二选一即可,未给的那个会用同名值补齐):
pixi import --format=pypi-txt --feature=my-feature1 requirements.txt
导入后清单新增:
[feature.my-feature1.pypi-dependencies]
cowpy = "*"
array-api-extra = ">=0.8"
[environments]
my-feature1 = { features = ["my-feature1"], no-default-feature = true }
要点:
- 文件中的每个依赖都会进入对应 feature 的
pypi-dependencies表; - 若目标环境名此前不存在,创建的环境会设置
no-default-feature; - 与
conda-env格式一样,支持导入到已存在的 feature/environment(含default),也支持--platform指定平台。
该格式的解析链路在源码中清晰可见(crates/pixi_cli/src/import.rs):用 uv_requirements_txt::RequirementsTxt::parse 读取文件,再经 convert_uv_requirements_txt_to_pep508 转换为 PEP 508 需求对象。当前实现有两个值得注意的限制:
- 不支持未命名(unnamed)需求,例如直接引用 URL/路径的条目会报错 "unnamed requirements are currently unsupported";
- 不支持 constraints 文件,若检测到 constraints 会告警并忽略(源码中
warn!("Constraints detected in input file, but these are currently unsupported..."))。
pixi init --import:初始化与导入一步完成
pixi import 需要先有工作区;如果连工作区都还没有,可以用 pixi init --import 把"初始化 + 导入"合并成一步。该选项在 docs/reference/cli/pixi/init.md 中描述为 "Environment.yml file to bootstrap the workspace",源码对应 crates/pixi_cli/src/init.rs 的 -i, --import <ENVIRONMENT_FILE> 参数。
沿用上面的 environment.yml,执行:
pixi init --import environment.yml
得到的工作区清单为:
[workspace]
authors = ["Lucas Colley <lucas.colley8@gmail.com>"]
channels = ["conda-forge"]
name = "simple-env"
platforms = ["osx-arm64"]
version = "0.1.0"
[tasks]
[dependencies]
python = "*"
[pypi-dependencies]
httpx = "*"
与 pixi import 的关键差异:
- 默认使用
defaultfeature 与环境,而不是按文件name新建 feature——等效于先pixi init再pixi import --feature=default environment.yml; - 工作区名称默认取自导入文件的
name字段(若文件声明了 name),而不是取自当前目录名; - 当前仅支持
conda-env格式,pypi-txt尚不能用于pixi init --import。
实现细节与已知边界(源码视角)
- 内联内容的默认 feature 处理:当未指定
--feature时,导入内容以内联方式写入环境。为避免新环境意外带上工作区defaultfeature,源码会在清单编辑前预先创建带no-default-feature=true的新环境(crates/pixi_cli/src/import.rs)。 - channels 的合并与去重:
CondaEnvFile::to_manifest会合并文件channels字段与依赖中带 channel 前缀(如pytorch::torchvision)所隐含的 channel,并做去重;若文件未声明 channels,则回退到配置的默认 channels(crates/pixi_utils/src/conda_environment_file.rs)。特别的,defaults会被展开为main、r、msys2三个具体 channel(parse_channels函数)。 sel(...)选择器暂不支持:CondaEnvFile::from_path会跳过包含 micromamba 风格- sel(...)的行并告警,提示用户手工补充依赖(crates/pixi_utils/src/conda_environment_file.rs)。variables段暂未导入:源码中留有 TODO 注释,environment.yml的variables段当前不会写入清单。- 无 dry-run:源码注释表明 dry-run 逻辑尚未实现,导入是直接写清单的操作。
- 解析正确性由单元测试保障:crates/pixi_utils/src/conda_environment_file.rs 中的
test_parse_conda_env_file验证了 channel 提取、MatchSpec转换与 PEP 508 解析;test_import_from_env_yamls则对tests/environment_yamls目录下的多个真实环境文件做快照测试。
小结
pixi import 是连接 Conda/PyPI 生态既有资产与 Pixi 工作区清单的桥梁:conda-env 格式把 environment.yml 的 channels、conda 依赖与 pip 子块分别映射为 feature 的 channels、dependencies 与 pypi-dependencies;pypi-txt 格式把 requirements.txt 映射为 pypi-dependencies。配合 --feature / --environment 可完成环境合并,配合 --platform 可控制平台范围,而 pixi init --import 则让新工作区的创建直接由旧环境文件驱动。对于完整的参数语义,可继续查阅 import.md 与 init.md 参考文档,更丰富的逐步演示见 import 教程。