开发工具CLI包管理器任务调度【免费下载链接】pixiPowerful system-level package manager for Linux, macOS and Windows written in Rust – building on top of the Conda ecosystem.项目地址https://gitcode.com/gh_mirrors/pi/pixi点击查看免费下载Pixi 的pixi-build-python是专为 Python 项目设计的 conda 构建后端它读取标准pyproject.tomlPEP 517/518自动生成 conda 配方recipe并完成从构建、安装到产出 noarch 或平台特定 conda 包的全流程。本文完整讲解它的启用方式、[package.build.config]下全部配置选项的语义与合并规则、可选的 PyPI-to-conda 依赖自动映射机制、构建脚本与安装器选择逻辑并结合本仓库中 pixi_build_python crate 的源码config.rs、build_script.rs、pypi_mapping.rs、metadata.rs逐项印证实现细节。读完后你将能独立把一个标准 Python 包纯 Python、带 C 扩展、Rust 扩展乃至 abi3 包配置进 Pixi 的构建工作流。注意pixi-build目前仍是预览preview特性接口在稳定前可能变化。因此 Pixi 要求用户显式在workspace.preview中开启该功能[workspace] preview [pixi-build]核心能力一览该后端负责把 Python 项目自动转换成 conda 包能力包括PEP 517/518 兼容支持现代 Python 打包标准直接消费pyproject.tomlPyPI-to-conda 映射可选开启把pyproject.toml中的project.dependencies与build-system.requires映射为 conda 包详见下文ignore-pypi-mapping与 自动映射 两节自动编译器检测识别maturin、setuptools-rust等构建工具并自动补充所需编译器跨平台支持在 Linux、macOS、Windows 上行为一致灵活的安装器默认使用uv也可通过installer选项切换为pip。基础用法在pixi.toml中为包声明构建配置即可启用 Python 后端[package] name python_package version 0.1.0 [package.build.backend] name pixi-build-python channels [https://prefix.dev/conda-forge]如果源码目录中存在pyproject.tomlPixi 的自动 PyPI 依赖映射特性会自动为你选中该后端否则需要把后端显式加入包的[host-dependencies][package.host-dependencies] hatchling *必需依赖后端会自动把以下构建工具加入环境这是 Python 后端与 CMake/Rust 后端的重要差异构建工具加入的是host需求而非 build 需求见 main.rs 的实现pythonPython 解释器uv默认的 Python 包安装器当配置installer pip时改为pip。如果你需要指定具体版本可在[host-dependencies]中补充约束[package.host-dependencies] python 3.14.*在哪里约束 Python 版本请把 Python 版本约束写在[package.host-dependencies]中而不是[package.build-dependencies]。后端总是会把python同时加入 host 与 run 需求你在[package.host-dependencies]给出的 spec 会在求解器中与之求交集因此约束既被满足也会传播到产物包的 run 需求上源码中对应逻辑见 main.rs后端先从pyproject.toml读取requires-python生成python {requires_python}约束再同时 push 到 host 与 run 两个需求列表。版本约束也可以来自pyproject.toml的project.requires-python。当ignore-pyproject-manifest设为true时该值被忽略此时请改在[package.host-dependencies]中指定版本。配置选项全解所有自定义行为都通过[package.build.config]配置。下表先给出全局视图类型、默认值、跨平台合并行为随后逐项深入配置项类型默认值目标合并行为noarchBooleantrue指定了 compilers 时除外Overwrite平台特定值覆盖基础值envMapString, String{}Merge平台变量按 key 覆盖基础变量其余合并debug-dir已废弃——extra-input-globsArray[]Overwrite平台 globs 完全替换基础 globscompilersArray[]Overwrite平台 compilers 完全替换基础配置abi3BooleanfalseOverwrite平台特定值优先installerStringuv/pipuvOverwrite平台特定值优先extra-argsArray[]Overwrite平台特定值完全替换基础值skip-pyc-compilationBoolean | Array未设置不跳过任何文件Overwrite平台特定值优先ignore-pyproject-manifestBooleanfalseOverwrite平台特定值优先ignore-pypi-mappingBooleantrueOverwrite平台特定值优先pypi-conda-mapMapString, String | false未设置Merge平台条目按 key 覆盖或扩展基础条目这些合并规则与目标平台配置[package.build.target.platform.config]一一对应均实现在 config.rs 的merge_with_target_config中并有完整的单元测试覆盖如test_merge_with_target_config、test_merge_pypi_conda_map_per_key可从源码确认每个字段的覆盖优先级。noarch类型Boolean默认true除非指定了 compilers目标合并行为Overwrite——平台特定的 noarch 设置优先于基础设置控制构建平台无关noarch包还是平台特定包。后端根据是否配置了 compilers 推导能否构建 noarch一旦指定了 compilers后端即假定构建过程中会产生原生扩展这类扩展通常是平台相关的因此包会被构建为平台特定包未指定 compilers 时默认noarch true即构建纯 Python noarch 包。[package.build.config] noarch false # 构建平台特定包目标平台特定配置可以覆盖基础配置[package.build.config] noarch true [package.build.target.win-64.config] noarch false # Windows 需要平台特定构建 # win-64 的最终结果false源码中的判定顺序main.rs为显式noarch true优先其次显式noarch false两者均未指定时若存在 compilers 则构建平台特定包否则回退为 noarch。env类型MapString, String默认{}目标合并行为Merge——平台同名环境变量覆盖基础变量其余变量合并保留构建过程中设置的环境变量在包安装时同样可用[package.build.config] env { SETUPTOOLS_SCM_PRETEND_VERSION 1.0.0 }目标平台配置与基础配置按变量名合并[package.build.config] env { PYTHONPATH /base/path, COMMON_VAR base } [package.build.target.win-64.config] env { COMMON_VAR windows, WIN_SPECIFIC value } # win-64 的最终结果{ PYTHONPATH /base/path, COMMON_VAR windows, WIN_SPECIFIC value }关于变量引用的重要提醒Pixi不会展开env中的变量引用值会原样传给构建 shell只有 shell 自身能解析时才生效。Linux/macOS 构建经bash运行可展开$PREFIXWindows 构建经cmd.exe运行展开%PREFIX%$PREFIX会保留为字面文本。当两种平台都需要时请使用目标平台特定配置[package.build.target.unix.config] env { MY_INCLUDE_DIR $PREFIX/include } [package.build.target.win.config] env { MY_INCLUDE_DIR %PREFIX%\\Library\\include }注意${{ PREFIX }}不是替代方案——env中的模板是在配方求值时渲染的此时构建前缀尚不存在模板语法只适用于构建脚本内部。debug-dir该选项已废弃。后端始终会把 JSON-RPC 请求/响应日志与生成的中间配方写到工作目录下的debug子目录例如work_directory/debug。若配置中仍出现debug-dir会发出警告提示其不再有任何效果。从源码看PythonBackendConfig仍保留该字段config.rs并兼容debug_dir别名但仅用于向后兼容解析不再参与行为控制。extra-input-globs类型ArrayString默认[]目标合并行为Overwrite——平台特定 globs 完全替换基础 globs额外的输入文件 glob 模式用于增量构建检测。默认输入 globs 已包含 Python 源文件、配置文件setup.py、pyproject.toml等及其他构建相关文件。源码中默认 globs 的完整清单见 main.rs基础 globs 包括setup.py、setup.cfg、pyproject.toml、requirements*.txt、Pipfile、Pipfile.lock、poetry.lock、tox.ini非 editable 构建额外跟踪**/*.py根据 compilers 补充源码 globsrust→**/*.rs、**/Cargo.tomlcxx→**/*.{cc,cxx,cpp,hpp,hxx}c→**/*.{c,h}若解析出的包中包含cython还会追加**/*.{pyx,pxd,pxi}main.rs。[package.build.config] extra-input-globs [ data/**/*, templates/*.html, *.md ]目标平台特定配置完全替换基础配置[package.build.config] extra-input-globs [*.py] [package.build.target.win-64.config] extra-input-globs [*.py, *.dll, *.pyd, windows-resources/**/*] # win-64 的最终结果[*.py, *.dll, *.pyd, windows-resources/**/*]compilers类型ArrayString默认[]无编译器目标合并行为Overwrite——平台特定 compilers 完全替换基础配置构建使用的编译器列表。绝大多数纯 Python 包不需要编译器但包含 C 扩展或其他编译组件的包需要。后端通过 conda-forge 的编译器基础设施自动生成对应的编译器依赖编译器如何映射到 conda 依赖、平台特定行为等细节见 Compilers Documentation。[package.build.config] compilers [c, cxx]目标平台特定配置完全替换基础配置[package.build.config] compilers [] [package.build.target.win-64.config] compilers [c, cxx] # win-64 的最终结果[c, cxx]仅 Windows纯 Python 与扩展包的区别Python 后端默认无编译器[]因为大多数 Python 包是纯 Python 的。这与 CMake 等后端默认[cxx]不同。仅在包含 C 扩展等编译组件时才需显式指定# 纯 Python 包默认行为 [package.build.config] # 无需编译器默认为 [] # 带 C 扩展的 Python 包 [package.build.config] compilers [c, cxx]自动编译器检测后端会检查build-system.requires并自动补全所需编译器映射表见 pypi_mapping.rsmaturin→rustsetuptools-rust→rust自动检测到的编译器会与显式配置的编译器合并去重逻辑见 main.rs。只有构建工具未被自动检测覆盖时才需要手动指定 compilers。abi3类型Boolean默认false目标合并行为Overwrite——平台特定设置优先控制包是否使用 Python 稳定 ABIabi3。设为true时Pixi 会把配方标记为build.python.version_independent: true把python-abi3加入 host 需求抑制host: python产生的常规 CPython ABI run exports。这一行为遵循 CEP 20conda 生态对 abi3 Python 包的支持规范。python-abi3的版本由requires-python的下界推导requires-python 3.9→python-abi3 3.9.*requires-python 3.11,4→python-abi3 3.11.*未指定requires-python时默认python-abi3 3.9.*conda-forge 上可用的最老python-abi3包该推导逻辑在 main.rs 的python_abi3_spec_from_requires_python中实现取第一个运算符的版本下界并截断到 major.minor 后拼上.*。如果 host 需求中已声明python-abi3Pixi 不会重复添加同时后端会把python加入ignore_run_exports.from_package避免继承 CPython ABI 固定版本main.rs。[package.build.config] abi3 true compilers [c]与 noarch 不兼容abi3 true与noarch true同时设置会报错因为稳定 ABI 只对有编译扩展的包有意义校验见 main.rs。installer类型Stringuv或pip默认uv目标合并行为Overwrite——平台特定设置优先选择用于把构建出的 wheel 安装进前缀的工具。所选安装器会被自动加入 host 依赖Installer::package_name把uv/pip映射为 conda 包名见 build_script.rs。[package.build.config] installer pip行为变更提醒旧版本后端会在 build 或 host 依赖中出现pip时自动选用pip。现在不再生效——若要用pip请在配置中显式设置installer pip。配置反序列化与校验非法值如conda会报错见 config.rs 的测试。extra-args类型ArrayString默认[]目标合并行为Overwrite——平台特定值完全替换基础值传给所选安装器默认uv或选中的pip的额外参数。一个典型用途是传给pip的--config-settings参数[package.build.config] extra-args [-Cbuilddirmybuilddir]目标平台特定配置完全替换基础配置[package.build.config] extra-args [-Cbuilddirmybuilddir] [package.build.target.win-64.config] extra-args [-Cbuilddirfoo] # win-64 的最终结果[-Cbuilddirfoo]extra_args最终会被注入构建脚本模板的OPTIONS列表见 build_script.j2与-vv、--no-deps等固定参数拼接。skip-pyc-compilation类型Boolean | ArrayString默认未设置不跳过任何文件目标合并行为Overwrite——平台特定设置优先控制包安装过程中.py文件是否被编译为.pyc字节码。可用于减小包体积或避免不必要的字节码缓存。接受true跳过全部.pyc编译或 glob 模式列表选择性跳过# 跳过所有 .pyc 编译 [package.build.config] skip-pyc-compilation true# 仅对特定路径跳过 .pyc 编译 [package.build.config] skip-pyc-compilation [tests/**, benchmarks/**]目标平台特定配置完全替换基础配置[package.build.config] skip-pyc-compilation true [package.build.target.win-64.config] skip-pyc-compilation [tests/**] # win-64 的最终结果[tests/**]源码中用SkipPycCompilation枚举表示两种形态true会被展开为[**/*.py]全局模式glob 列表原样使用config.rs最终写入配方的build.python.skip_pyc_compilationmain.rs。ignore-pyproject-manifest类型Boolean默认false目标合并行为Overwrite——平台特定设置优先控制是否忽略pyproject.toml清单文件完全依赖项目模型project model提供包元数据。设为true时后端不再从pyproject.toml提取 name、version、description、license、URL 等元数据而只使用 Pixi 项目模型中提供的信息[package.build.config] ignore-pyproject-manifest true # 忽略 pyproject.toml 元数据当你希望通过 Pixi 项目配置完全掌控包元数据或pyproject.toml中的元数据与 conda 包需求冲突时该选项很有用。目标平台特定配置可覆盖基础配置[package.build.config] ignore-pyproject-manifest false [package.build.target.win-64.config] ignore-pyproject-manifest true # 仅在 Windows 上忽略 pyproject.toml # win-64 的最终结果true默认的元数据提取行为ignore-pyproject-manifest false时由 metadata.rs 中的PyprojectMetadataProvider实现自动从pyproject.toml提取name来自project.nameversion来自project.versiondescription/summary来自project.descriptionlicense来自project.license支持 text、file 或 SPDX 格式非合法 SPDX 表达式会记录 warning 并返回 Nonelicense-files来自license.file与license-files字段相对路径会被解析为绝对路径out-of-source 构建时 rattler-build 需要homepage来自project.urls.Homepagerepository来自project.urls.Repository、project.urls.Source或project.urls.Source Codedocumentation来自project.urls.Documentation或project.urls.Docs这些元数据会自动写入生成的 conda 配方pyproject.toml文件本身也会被加入输入 globs 以支持增量构建检测。若源码目录缺少pyproject.toml后端会以明确的错误终止MissingPyProjectToml提示添加 PEP 517/518 清单或改用其他后端。ignore-pypi-mapping类型Boolean默认true目标合并行为Overwrite——平台特定设置优先控制是否忽略自动 PyPI-to-conda 依赖映射。为true默认时pyproject.toml中的依赖不会被自动映射为 conda 包为false时启用自动映射[package.build.config] ignore-pypi-mapping false # 启用自动 PyPI-to-conda 映射默认值说明该选项目前默认true映射关闭以避免破坏既有配置。未来版本中默认值将改为false映射开启。若现在就想启用自动依赖映射请显式设置ignore-pypi-mapping false。源码默认值见 config.rs。目标平台特定配置可覆盖基础配置[package.build.config] ignore-pypi-mapping false [package.build.target.win-64.config] ignore-pypi-mapping true # 仅在 Windows 上禁用映射 # win-64 的最终结果truepypi-conda-map类型MapString, String | false默认未设置目标合并行为Merge——平台条目按 key 覆盖或扩展基础条目用户自定义的 PyPI-to-conda 名称映射覆盖以 PyPI 包名为 key。字符串值把该包映射到对应的 conda 包名false则把该依赖从生成的配方中剔除。这些条目在查询映射服务之前被优先采纳因此永远不需要网络访问未覆盖的包照常回退到映射服务。该选项仅在ignore-pypi-mapping false时生效否则无效并输出 warning见 main.rs。覆盖同时作用于两趟映射project.dependenciesrun 依赖与build-system.requireshost 依赖。与conda-pypi-map形状不同pypi-conda-map并非 workspace 层conda-pypi-map的 schema 镜像。它是扁平的PyPI 名 → conda 名覆盖表因为构建后端把每个 Python 需求至多转换为一条 conda 配方依赖而 workspace 的conda-pypi-map按 channel 组织可以把一个 conda 包映射到多个 PyPI 名因为它用于判断哪些已安装的 conda 包能够满足 PyPI 需求。[package.build.config] ignore-pypi-mapping false pypi-conda-map { torch pytorch, my-internal-pkg false }平台条目与基础条目按 key 合并[package.build.config] pypi-conda-map { torch pytorch } [package.build.target.linux-64.config] pypi-conda-map { nvidia-cublas-cu12 false } # linux-64 的最终结果{ torch pytorch, nvidia-cublas-cu12 false }实现层面config.rsPypiCondaMapEntry是一个自定义反序列化枚举——字符串被解析为CondaNamefalse/null被解析为Skip而true是不合法的会报错 trueis not supported。apply_user_mappypi_mapping.rs会先把 key 规范化为 PEP 508 包名因此My_Pkg能匹配my-pkg再逐条应用Skip静默丢弃依赖映射名非法时不会静默丢包而是告警并回退到映射服务用户映射的依赖同样经过环境标记marker求值。自动 PyPI 依赖映射Python 后端可以把pyproject.toml中的 PyPI 依赖自动映射为对应的 conda 包免去在pyproject.toml与pixi.toml中重复维护依赖清单。需显式开启该特性当前默认关闭。启用方式[package.build.config] ignore-pypi-mapping false工作原理后端从pyproject.toml的两个位置读取依赖project.dependencies→ 加入 condarun依赖build-system.requires→ 加入 condahost依赖对每个 PyPI 包后端先查用户自定义的pypi-conda-map覆盖再查询映射服务以获取对应的 conda-forge 包名映射结果在本地缓存 24 小时以提升性能。源码细节pypi_mapping.rs映射服务基地址为https://conda-mapping.prefix.dev/pypi-to-conda-v1MAPPING_BASE_URL缓存目录为缓存区下的pypi-conda-mapping/channel/pkg.jsonTTL 为24 * 60 * 60秒映射按 channel 逐个尝试使用第一个成功映射出依赖的 channelPEP 440 运算符会被转换为 conda 兼容形式如→~保留。示例给定如下pyproject.toml[project] name my-package version 1.0.0 dependencies [ requests2.28, pydantic2.0,3.0, ] [build-system] requires [hatchling] build-backend hatchling.build后端会自动添加requests 2.28与pydantic 2.0,3.0到run依赖hatchling到host依赖。与 manifest 依赖结合pixi.toml中声明的依赖会与从pyproject.toml推断出的依赖合并若在[package.run-dependencies]中写了requests 2.30则该 spec 与映射得到的requests2.28会同时进入配方并在求解器中求交集未在pixi.toml中声明的依赖会从pyproject.toml补入。若要完全摆脱pyproject.toml中的版本边界请用ignore-pypi-mapping关闭映射并在pixi.toml中声明依赖。行为变更提醒旧版本后端在同一包已声明于pixi.toml时会跳过映射出的pyproject.tomlspec。现在两个 spec 都会进入配方并求交集冲突的边界会以求解器错误的形式呈现而不再被静默覆盖。已知限制环境标记marker仅部分支持例如requests2.28; python_version 3.8。目前只有platform_system、os_name、platform_machine和sys_platform会被检查求值。源码实现见 pypi_mapping.rsmarker 中含有任何非系统字段python_version、python_full_version、implementation_*等时整条依赖被保守排除noarch 平台下所有带 marker 的依赖都会被排除noarch 包必须平台无关仅含系统字段的 marker 则针对目标平台求值例如sys_platform win32在 linux-64 上求值为 false 从而跳过。相关行为均有单元测试覆盖如test_marker_evaluation_linux、test_marker_python_full_version_excluded。URL 依赖被跳过例如package https://...无 conda-forge 映射的包记录 warning 并跳过可用pypi-conda-map显式映射或用false剔除。构建流程Python 后端的构建流程分为四步安装器选择默认使用uv配置installer pip时使用pip环境设置配置构建所需 Python 环境变量包安装以固定参数执行所选安装器--no-deps不安装依赖依赖由 conda 处理--no-build-isolation使用 conda 环境进行构建-vv输出详细日志便于调试包创建创建 noarch 或平台特定 conda 包。上述参数在构建脚本模板 build_script.j2 中硬编码还包含--no-index以及 editable 构建时的--editableuv路径使用uv pip install --python ... --reinstallpip路径使用python -m pip install --force-reinstall由 build_script.rs 中的BuildScriptContext通过 minijinja 渲染最终写入配方的 build scriptmain.rs。安装器选择与 uv 缓存位置安装器由installer配置决定并自动加入 host 依赖[package.build.config] installer pipuv缓存位置构建脚本在清理过的环境中运行因此uv无法自行感知UV_CACHE_DIR。后端因此会显式设置它优先级从高到低env中配置的UV_CACHE_DIR适合让单个包使用自己的缓存config.env最后应用、优先级最高pixi自身运行环境中导出的UV_CACHE_DIRpixi 缓存目录下的uv-cache子目录跟随PIXI_CACHE_DIR与RATTLER_CACHE_DIR迁移。否则在 Unix 上缓存会落入一次性构建目录每次构建都从空缓存开始在 Windows 上则会落入默认的用户级位置即使 pixi 缓存已被移动到别处也不跟随。源码见 main.rs 的uv_cache_dir函数且有test_uv_cache_dir_defaults_to_the_pixi_cache、test_uv_cache_dir_prefers_the_environment等单元测试锁定行为。可编辑安装Editable Installations在 profiles 功能落地之前可编辑安装的配置方式有限。当前行为如下安装包时例如pixi installeditable为true构建包时例如pixi publisheditable为false设置环境变量BUILD_EDITABLE_PYTHON为true或false可强制指定行为。实现上effective_editablemain.rs读取该环境变量true强制 editable其余任何值强制非 editable未设置时沿用传入参数该值同时决定构建脚本是否附加--editable以及输入 globs 是否跟踪**/*.pyeditable 构建不追踪避免把源码烤进包中却未被 globs 跟踪。默认变体Windows在 Windows 平台上后端自动设置如下默认变体c_compilervs2022——Visual Studio 2022 C 编译器cxx_compilervs2022——Visual Studio 2022 C 编译器这些变体在你通过[package.build.config.compilers]指定编译器时使用。注意设置这些默认变体不会自动向构建添加编译器——你仍需显式配置要用的编译器。默认变体逻辑来自 main.rs 的default_variants其调用pixi_build_backend::compilers::default_compiler_variants。该默认值对齐 conda-forge 转向 Visual Studio 2022 的决策且 Visual Studio 2019 的主流支持已于 2024 年结束vs2022在现代 GitHub runner 与构建环境中支持更广泛。如需覆盖默认值可通过pixi.toml中的[workspace.build-variants]显式设置变体[workspace.build-variants] c_compiler [vs2019] cxx_compiler [vs2019]关于变体系统的更完整介绍见 variants 文档。局限性与适用边界要求项目是带pyproject.toml的 PEP 517/518 兼容 Python 项目相比直接基于配方recipe的方式复杂构建定制能力有限可编辑安装的配置方式有限见上文。参见Building Python Packages——用 Pixi 构建 Python 包的入门教程Build Backends 总览——Pixi 构建后端协议与可用后端清单pixi-build-cmake、pixi-build-rattler-build、pixi-build-ros、pixi-build-r、pixi-build-rust、pixi-build-mojoCompilers Documentation——conda-forge 编译器基础设施、可用编译器与平台行为dependency_types——build / host / run 依赖类型说明pixi_manifest——Pixi 清单 schema 参考build表、build-variants、conda-pypi-map等赞分享开发工具CLI包管理器任务调度【免费下载链接】pixiPowerful system-level package manager for Linux, macOS and Windows written in Rust – building on top of the Conda ecosystem.项目地址https://gitcode.com/gh_mirrors/pi/pixi点击查看免费下载相关推荐Pixi 构建后端 pixi-build-rust用 Cargo 自动生成 Conda 包Pixi 构建后端 pixi build rust用 Cargo 自动生成 Conda 包 pixi build rust 是 Pixi 的 Rust 项目构开发工具CLI包管理器任务调度Escrcpy 安卓屏幕镜像到电脑完整指南3 分钟 USB 投屏 无线配对步骤教程Escrcpy 安卓屏幕镜像到电脑完整指南3 分钟 USB 投屏 无线配对步骤教程 Escrcpy 是一款基于 scrcpyAndroid 屏幕投射与操开发工具CLI包管理器任务调度使用 Pixi 的 build 功能从源码构建 conda 包Manifest 配置、后端机制与发布实战使用 Pixi 的 build 功能从源码构建 conda 包Manifest 配置、后端机制与发布实战 Pixi 不仅能管理工作流与环境还能直接从源码构建开发工具CLI包管理器任务调度上一篇Rust桌面应用Tauri框架与跨平台GUI下一篇BiliDrive安全机制详解META URL如何保障你的文件不被他人访问创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pixi-build-python 构建后端深度指南：用 Pixi 将 PEP 517/518 Python 项目一键打包为 conda 包
开发工具CLI包管理器任务调度【免费下载链接】pixiPowerful system-level package manager for Linux, macOS and Windows written in Rust – building on top of the Conda ecosystem.项目地址https://gitcode.com/gh_mirrors/pi/pixi点击查看免费下载Pixi 的pixi-build-python是专为 Python 项目设计的 conda 构建后端它读取标准pyproject.tomlPEP 517/518自动生成 conda 配方recipe并完成从构建、安装到产出 noarch 或平台特定 conda 包的全流程。本文完整讲解它的启用方式、[package.build.config]下全部配置选项的语义与合并规则、可选的 PyPI-to-conda 依赖自动映射机制、构建脚本与安装器选择逻辑并结合本仓库中 pixi_build_python crate 的源码config.rs、build_script.rs、pypi_mapping.rs、metadata.rs逐项印证实现细节。读完后你将能独立把一个标准 Python 包纯 Python、带 C 扩展、Rust 扩展乃至 abi3 包配置进 Pixi 的构建工作流。注意pixi-build目前仍是预览preview特性接口在稳定前可能变化。因此 Pixi 要求用户显式在workspace.preview中开启该功能[workspace] preview [pixi-build]核心能力一览该后端负责把 Python 项目自动转换成 conda 包能力包括PEP 517/518 兼容支持现代 Python 打包标准直接消费pyproject.tomlPyPI-to-conda 映射可选开启把pyproject.toml中的project.dependencies与build-system.requires映射为 conda 包详见下文ignore-pypi-mapping与 自动映射 两节自动编译器检测识别maturin、setuptools-rust等构建工具并自动补充所需编译器跨平台支持在 Linux、macOS、Windows 上行为一致灵活的安装器默认使用uv也可通过installer选项切换为pip。基础用法在pixi.toml中为包声明构建配置即可启用 Python 后端[package] name python_package version 0.1.0 [package.build.backend] name pixi-build-python channels [https://prefix.dev/conda-forge]如果源码目录中存在pyproject.tomlPixi 的自动 PyPI 依赖映射特性会自动为你选中该后端否则需要把后端显式加入包的[host-dependencies][package.host-dependencies] hatchling *必需依赖后端会自动把以下构建工具加入环境这是 Python 后端与 CMake/Rust 后端的重要差异构建工具加入的是host需求而非 build 需求见 main.rs 的实现pythonPython 解释器uv默认的 Python 包安装器当配置installer pip时改为pip。如果你需要指定具体版本可在[host-dependencies]中补充约束[package.host-dependencies] python 3.14.*在哪里约束 Python 版本请把 Python 版本约束写在[package.host-dependencies]中而不是[package.build-dependencies]。后端总是会把python同时加入 host 与 run 需求你在[package.host-dependencies]给出的 spec 会在求解器中与之求交集因此约束既被满足也会传播到产物包的 run 需求上源码中对应逻辑见 main.rs后端先从pyproject.toml读取requires-python生成python {requires_python}约束再同时 push 到 host 与 run 两个需求列表。版本约束也可以来自pyproject.toml的project.requires-python。当ignore-pyproject-manifest设为true时该值被忽略此时请改在[package.host-dependencies]中指定版本。配置选项全解所有自定义行为都通过[package.build.config]配置。下表先给出全局视图类型、默认值、跨平台合并行为随后逐项深入配置项类型默认值目标合并行为noarchBooleantrue指定了 compilers 时除外Overwrite平台特定值覆盖基础值envMapString, String{}Merge平台变量按 key 覆盖基础变量其余合并debug-dir已废弃——extra-input-globsArray[]Overwrite平台 globs 完全替换基础 globscompilersArray[]Overwrite平台 compilers 完全替换基础配置abi3BooleanfalseOverwrite平台特定值优先installerStringuv/pipuvOverwrite平台特定值优先extra-argsArray[]Overwrite平台特定值完全替换基础值skip-pyc-compilationBoolean | Array未设置不跳过任何文件Overwrite平台特定值优先ignore-pyproject-manifestBooleanfalseOverwrite平台特定值优先ignore-pypi-mappingBooleantrueOverwrite平台特定值优先pypi-conda-mapMapString, String | false未设置Merge平台条目按 key 覆盖或扩展基础条目这些合并规则与目标平台配置[package.build.target.platform.config]一一对应均实现在 config.rs 的merge_with_target_config中并有完整的单元测试覆盖如test_merge_with_target_config、test_merge_pypi_conda_map_per_key可从源码确认每个字段的覆盖优先级。noarch类型Boolean默认true除非指定了 compilers目标合并行为Overwrite——平台特定的 noarch 设置优先于基础设置控制构建平台无关noarch包还是平台特定包。后端根据是否配置了 compilers 推导能否构建 noarch一旦指定了 compilers后端即假定构建过程中会产生原生扩展这类扩展通常是平台相关的因此包会被构建为平台特定包未指定 compilers 时默认noarch true即构建纯 Python noarch 包。[package.build.config] noarch false # 构建平台特定包目标平台特定配置可以覆盖基础配置[package.build.config] noarch true [package.build.target.win-64.config] noarch false # Windows 需要平台特定构建 # win-64 的最终结果false源码中的判定顺序main.rs为显式noarch true优先其次显式noarch false两者均未指定时若存在 compilers 则构建平台特定包否则回退为 noarch。env类型MapString, String默认{}目标合并行为Merge——平台同名环境变量覆盖基础变量其余变量合并保留构建过程中设置的环境变量在包安装时同样可用[package.build.config] env { SETUPTOOLS_SCM_PRETEND_VERSION 1.0.0 }目标平台配置与基础配置按变量名合并[package.build.config] env { PYTHONPATH /base/path, COMMON_VAR base } [package.build.target.win-64.config] env { COMMON_VAR windows, WIN_SPECIFIC value } # win-64 的最终结果{ PYTHONPATH /base/path, COMMON_VAR windows, WIN_SPECIFIC value }关于变量引用的重要提醒Pixi不会展开env中的变量引用值会原样传给构建 shell只有 shell 自身能解析时才生效。Linux/macOS 构建经bash运行可展开$PREFIXWindows 构建经cmd.exe运行展开%PREFIX%$PREFIX会保留为字面文本。当两种平台都需要时请使用目标平台特定配置[package.build.target.unix.config] env { MY_INCLUDE_DIR $PREFIX/include } [package.build.target.win.config] env { MY_INCLUDE_DIR %PREFIX%\\Library\\include }注意${{ PREFIX }}不是替代方案——env中的模板是在配方求值时渲染的此时构建前缀尚不存在模板语法只适用于构建脚本内部。debug-dir该选项已废弃。后端始终会把 JSON-RPC 请求/响应日志与生成的中间配方写到工作目录下的debug子目录例如work_directory/debug。若配置中仍出现debug-dir会发出警告提示其不再有任何效果。从源码看PythonBackendConfig仍保留该字段config.rs并兼容debug_dir别名但仅用于向后兼容解析不再参与行为控制。extra-input-globs类型ArrayString默认[]目标合并行为Overwrite——平台特定 globs 完全替换基础 globs额外的输入文件 glob 模式用于增量构建检测。默认输入 globs 已包含 Python 源文件、配置文件setup.py、pyproject.toml等及其他构建相关文件。源码中默认 globs 的完整清单见 main.rs基础 globs 包括setup.py、setup.cfg、pyproject.toml、requirements*.txt、Pipfile、Pipfile.lock、poetry.lock、tox.ini非 editable 构建额外跟踪**/*.py根据 compilers 补充源码 globsrust→**/*.rs、**/Cargo.tomlcxx→**/*.{cc,cxx,cpp,hpp,hxx}c→**/*.{c,h}若解析出的包中包含cython还会追加**/*.{pyx,pxd,pxi}main.rs。[package.build.config] extra-input-globs [ data/**/*, templates/*.html, *.md ]目标平台特定配置完全替换基础配置[package.build.config] extra-input-globs [*.py] [package.build.target.win-64.config] extra-input-globs [*.py, *.dll, *.pyd, windows-resources/**/*] # win-64 的最终结果[*.py, *.dll, *.pyd, windows-resources/**/*]compilers类型ArrayString默认[]无编译器目标合并行为Overwrite——平台特定 compilers 完全替换基础配置构建使用的编译器列表。绝大多数纯 Python 包不需要编译器但包含 C 扩展或其他编译组件的包需要。后端通过 conda-forge 的编译器基础设施自动生成对应的编译器依赖编译器如何映射到 conda 依赖、平台特定行为等细节见 Compilers Documentation。[package.build.config] compilers [c, cxx]目标平台特定配置完全替换基础配置[package.build.config] compilers [] [package.build.target.win-64.config] compilers [c, cxx] # win-64 的最终结果[c, cxx]仅 Windows纯 Python 与扩展包的区别Python 后端默认无编译器[]因为大多数 Python 包是纯 Python 的。这与 CMake 等后端默认[cxx]不同。仅在包含 C 扩展等编译组件时才需显式指定# 纯 Python 包默认行为 [package.build.config] # 无需编译器默认为 [] # 带 C 扩展的 Python 包 [package.build.config] compilers [c, cxx]自动编译器检测后端会检查build-system.requires并自动补全所需编译器映射表见 pypi_mapping.rsmaturin→rustsetuptools-rust→rust自动检测到的编译器会与显式配置的编译器合并去重逻辑见 main.rs。只有构建工具未被自动检测覆盖时才需要手动指定 compilers。abi3类型Boolean默认false目标合并行为Overwrite——平台特定设置优先控制包是否使用 Python 稳定 ABIabi3。设为true时Pixi 会把配方标记为build.python.version_independent: true把python-abi3加入 host 需求抑制host: python产生的常规 CPython ABI run exports。这一行为遵循 CEP 20conda 生态对 abi3 Python 包的支持规范。python-abi3的版本由requires-python的下界推导requires-python 3.9→python-abi3 3.9.*requires-python 3.11,4→python-abi3 3.11.*未指定requires-python时默认python-abi3 3.9.*conda-forge 上可用的最老python-abi3包该推导逻辑在 main.rs 的python_abi3_spec_from_requires_python中实现取第一个运算符的版本下界并截断到 major.minor 后拼上.*。如果 host 需求中已声明python-abi3Pixi 不会重复添加同时后端会把python加入ignore_run_exports.from_package避免继承 CPython ABI 固定版本main.rs。[package.build.config] abi3 true compilers [c]与 noarch 不兼容abi3 true与noarch true同时设置会报错因为稳定 ABI 只对有编译扩展的包有意义校验见 main.rs。installer类型Stringuv或pip默认uv目标合并行为Overwrite——平台特定设置优先选择用于把构建出的 wheel 安装进前缀的工具。所选安装器会被自动加入 host 依赖Installer::package_name把uv/pip映射为 conda 包名见 build_script.rs。[package.build.config] installer pip行为变更提醒旧版本后端会在 build 或 host 依赖中出现pip时自动选用pip。现在不再生效——若要用pip请在配置中显式设置installer pip。配置反序列化与校验非法值如conda会报错见 config.rs 的测试。extra-args类型ArrayString默认[]目标合并行为Overwrite——平台特定值完全替换基础值传给所选安装器默认uv或选中的pip的额外参数。一个典型用途是传给pip的--config-settings参数[package.build.config] extra-args [-Cbuilddirmybuilddir]目标平台特定配置完全替换基础配置[package.build.config] extra-args [-Cbuilddirmybuilddir] [package.build.target.win-64.config] extra-args [-Cbuilddirfoo] # win-64 的最终结果[-Cbuilddirfoo]extra_args最终会被注入构建脚本模板的OPTIONS列表见 build_script.j2与-vv、--no-deps等固定参数拼接。skip-pyc-compilation类型Boolean | ArrayString默认未设置不跳过任何文件目标合并行为Overwrite——平台特定设置优先控制包安装过程中.py文件是否被编译为.pyc字节码。可用于减小包体积或避免不必要的字节码缓存。接受true跳过全部.pyc编译或 glob 模式列表选择性跳过# 跳过所有 .pyc 编译 [package.build.config] skip-pyc-compilation true# 仅对特定路径跳过 .pyc 编译 [package.build.config] skip-pyc-compilation [tests/**, benchmarks/**]目标平台特定配置完全替换基础配置[package.build.config] skip-pyc-compilation true [package.build.target.win-64.config] skip-pyc-compilation [tests/**] # win-64 的最终结果[tests/**]源码中用SkipPycCompilation枚举表示两种形态true会被展开为[**/*.py]全局模式glob 列表原样使用config.rs最终写入配方的build.python.skip_pyc_compilationmain.rs。ignore-pyproject-manifest类型Boolean默认false目标合并行为Overwrite——平台特定设置优先控制是否忽略pyproject.toml清单文件完全依赖项目模型project model提供包元数据。设为true时后端不再从pyproject.toml提取 name、version、description、license、URL 等元数据而只使用 Pixi 项目模型中提供的信息[package.build.config] ignore-pyproject-manifest true # 忽略 pyproject.toml 元数据当你希望通过 Pixi 项目配置完全掌控包元数据或pyproject.toml中的元数据与 conda 包需求冲突时该选项很有用。目标平台特定配置可覆盖基础配置[package.build.config] ignore-pyproject-manifest false [package.build.target.win-64.config] ignore-pyproject-manifest true # 仅在 Windows 上忽略 pyproject.toml # win-64 的最终结果true默认的元数据提取行为ignore-pyproject-manifest false时由 metadata.rs 中的PyprojectMetadataProvider实现自动从pyproject.toml提取name来自project.nameversion来自project.versiondescription/summary来自project.descriptionlicense来自project.license支持 text、file 或 SPDX 格式非合法 SPDX 表达式会记录 warning 并返回 Nonelicense-files来自license.file与license-files字段相对路径会被解析为绝对路径out-of-source 构建时 rattler-build 需要homepage来自project.urls.Homepagerepository来自project.urls.Repository、project.urls.Source或project.urls.Source Codedocumentation来自project.urls.Documentation或project.urls.Docs这些元数据会自动写入生成的 conda 配方pyproject.toml文件本身也会被加入输入 globs 以支持增量构建检测。若源码目录缺少pyproject.toml后端会以明确的错误终止MissingPyProjectToml提示添加 PEP 517/518 清单或改用其他后端。ignore-pypi-mapping类型Boolean默认true目标合并行为Overwrite——平台特定设置优先控制是否忽略自动 PyPI-to-conda 依赖映射。为true默认时pyproject.toml中的依赖不会被自动映射为 conda 包为false时启用自动映射[package.build.config] ignore-pypi-mapping false # 启用自动 PyPI-to-conda 映射默认值说明该选项目前默认true映射关闭以避免破坏既有配置。未来版本中默认值将改为false映射开启。若现在就想启用自动依赖映射请显式设置ignore-pypi-mapping false。源码默认值见 config.rs。目标平台特定配置可覆盖基础配置[package.build.config] ignore-pypi-mapping false [package.build.target.win-64.config] ignore-pypi-mapping true # 仅在 Windows 上禁用映射 # win-64 的最终结果truepypi-conda-map类型MapString, String | false默认未设置目标合并行为Merge——平台条目按 key 覆盖或扩展基础条目用户自定义的 PyPI-to-conda 名称映射覆盖以 PyPI 包名为 key。字符串值把该包映射到对应的 conda 包名false则把该依赖从生成的配方中剔除。这些条目在查询映射服务之前被优先采纳因此永远不需要网络访问未覆盖的包照常回退到映射服务。该选项仅在ignore-pypi-mapping false时生效否则无效并输出 warning见 main.rs。覆盖同时作用于两趟映射project.dependenciesrun 依赖与build-system.requireshost 依赖。与conda-pypi-map形状不同pypi-conda-map并非 workspace 层conda-pypi-map的 schema 镜像。它是扁平的PyPI 名 → conda 名覆盖表因为构建后端把每个 Python 需求至多转换为一条 conda 配方依赖而 workspace 的conda-pypi-map按 channel 组织可以把一个 conda 包映射到多个 PyPI 名因为它用于判断哪些已安装的 conda 包能够满足 PyPI 需求。[package.build.config] ignore-pypi-mapping false pypi-conda-map { torch pytorch, my-internal-pkg false }平台条目与基础条目按 key 合并[package.build.config] pypi-conda-map { torch pytorch } [package.build.target.linux-64.config] pypi-conda-map { nvidia-cublas-cu12 false } # linux-64 的最终结果{ torch pytorch, nvidia-cublas-cu12 false }实现层面config.rsPypiCondaMapEntry是一个自定义反序列化枚举——字符串被解析为CondaNamefalse/null被解析为Skip而true是不合法的会报错 trueis not supported。apply_user_mappypi_mapping.rs会先把 key 规范化为 PEP 508 包名因此My_Pkg能匹配my-pkg再逐条应用Skip静默丢弃依赖映射名非法时不会静默丢包而是告警并回退到映射服务用户映射的依赖同样经过环境标记marker求值。自动 PyPI 依赖映射Python 后端可以把pyproject.toml中的 PyPI 依赖自动映射为对应的 conda 包免去在pyproject.toml与pixi.toml中重复维护依赖清单。需显式开启该特性当前默认关闭。启用方式[package.build.config] ignore-pypi-mapping false工作原理后端从pyproject.toml的两个位置读取依赖project.dependencies→ 加入 condarun依赖build-system.requires→ 加入 condahost依赖对每个 PyPI 包后端先查用户自定义的pypi-conda-map覆盖再查询映射服务以获取对应的 conda-forge 包名映射结果在本地缓存 24 小时以提升性能。源码细节pypi_mapping.rs映射服务基地址为https://conda-mapping.prefix.dev/pypi-to-conda-v1MAPPING_BASE_URL缓存目录为缓存区下的pypi-conda-mapping/channel/pkg.jsonTTL 为24 * 60 * 60秒映射按 channel 逐个尝试使用第一个成功映射出依赖的 channelPEP 440 运算符会被转换为 conda 兼容形式如→~保留。示例给定如下pyproject.toml[project] name my-package version 1.0.0 dependencies [ requests2.28, pydantic2.0,3.0, ] [build-system] requires [hatchling] build-backend hatchling.build后端会自动添加requests 2.28与pydantic 2.0,3.0到run依赖hatchling到host依赖。与 manifest 依赖结合pixi.toml中声明的依赖会与从pyproject.toml推断出的依赖合并若在[package.run-dependencies]中写了requests 2.30则该 spec 与映射得到的requests2.28会同时进入配方并在求解器中求交集未在pixi.toml中声明的依赖会从pyproject.toml补入。若要完全摆脱pyproject.toml中的版本边界请用ignore-pypi-mapping关闭映射并在pixi.toml中声明依赖。行为变更提醒旧版本后端在同一包已声明于pixi.toml时会跳过映射出的pyproject.tomlspec。现在两个 spec 都会进入配方并求交集冲突的边界会以求解器错误的形式呈现而不再被静默覆盖。已知限制环境标记marker仅部分支持例如requests2.28; python_version 3.8。目前只有platform_system、os_name、platform_machine和sys_platform会被检查求值。源码实现见 pypi_mapping.rsmarker 中含有任何非系统字段python_version、python_full_version、implementation_*等时整条依赖被保守排除noarch 平台下所有带 marker 的依赖都会被排除noarch 包必须平台无关仅含系统字段的 marker 则针对目标平台求值例如sys_platform win32在 linux-64 上求值为 false 从而跳过。相关行为均有单元测试覆盖如test_marker_evaluation_linux、test_marker_python_full_version_excluded。URL 依赖被跳过例如package https://...无 conda-forge 映射的包记录 warning 并跳过可用pypi-conda-map显式映射或用false剔除。构建流程Python 后端的构建流程分为四步安装器选择默认使用uv配置installer pip时使用pip环境设置配置构建所需 Python 环境变量包安装以固定参数执行所选安装器--no-deps不安装依赖依赖由 conda 处理--no-build-isolation使用 conda 环境进行构建-vv输出详细日志便于调试包创建创建 noarch 或平台特定 conda 包。上述参数在构建脚本模板 build_script.j2 中硬编码还包含--no-index以及 editable 构建时的--editableuv路径使用uv pip install --python ... --reinstallpip路径使用python -m pip install --force-reinstall由 build_script.rs 中的BuildScriptContext通过 minijinja 渲染最终写入配方的 build scriptmain.rs。安装器选择与 uv 缓存位置安装器由installer配置决定并自动加入 host 依赖[package.build.config] installer pipuv缓存位置构建脚本在清理过的环境中运行因此uv无法自行感知UV_CACHE_DIR。后端因此会显式设置它优先级从高到低env中配置的UV_CACHE_DIR适合让单个包使用自己的缓存config.env最后应用、优先级最高pixi自身运行环境中导出的UV_CACHE_DIRpixi 缓存目录下的uv-cache子目录跟随PIXI_CACHE_DIR与RATTLER_CACHE_DIR迁移。否则在 Unix 上缓存会落入一次性构建目录每次构建都从空缓存开始在 Windows 上则会落入默认的用户级位置即使 pixi 缓存已被移动到别处也不跟随。源码见 main.rs 的uv_cache_dir函数且有test_uv_cache_dir_defaults_to_the_pixi_cache、test_uv_cache_dir_prefers_the_environment等单元测试锁定行为。可编辑安装Editable Installations在 profiles 功能落地之前可编辑安装的配置方式有限。当前行为如下安装包时例如pixi installeditable为true构建包时例如pixi publisheditable为false设置环境变量BUILD_EDITABLE_PYTHON为true或false可强制指定行为。实现上effective_editablemain.rs读取该环境变量true强制 editable其余任何值强制非 editable未设置时沿用传入参数该值同时决定构建脚本是否附加--editable以及输入 globs 是否跟踪**/*.pyeditable 构建不追踪避免把源码烤进包中却未被 globs 跟踪。默认变体Windows在 Windows 平台上后端自动设置如下默认变体c_compilervs2022——Visual Studio 2022 C 编译器cxx_compilervs2022——Visual Studio 2022 C 编译器这些变体在你通过[package.build.config.compilers]指定编译器时使用。注意设置这些默认变体不会自动向构建添加编译器——你仍需显式配置要用的编译器。默认变体逻辑来自 main.rs 的default_variants其调用pixi_build_backend::compilers::default_compiler_variants。该默认值对齐 conda-forge 转向 Visual Studio 2022 的决策且 Visual Studio 2019 的主流支持已于 2024 年结束vs2022在现代 GitHub runner 与构建环境中支持更广泛。如需覆盖默认值可通过pixi.toml中的[workspace.build-variants]显式设置变体[workspace.build-variants] c_compiler [vs2019] cxx_compiler [vs2019]关于变体系统的更完整介绍见 variants 文档。局限性与适用边界要求项目是带pyproject.toml的 PEP 517/518 兼容 Python 项目相比直接基于配方recipe的方式复杂构建定制能力有限可编辑安装的配置方式有限见上文。参见Building Python Packages——用 Pixi 构建 Python 包的入门教程Build Backends 总览——Pixi 构建后端协议与可用后端清单pixi-build-cmake、pixi-build-rattler-build、pixi-build-ros、pixi-build-r、pixi-build-rust、pixi-build-mojoCompilers Documentation——conda-forge 编译器基础设施、可用编译器与平台行为dependency_types——build / host / run 依赖类型说明pixi_manifest——Pixi 清单 schema 参考build表、build-variants、conda-pypi-map等赞分享开发工具CLI包管理器任务调度【免费下载链接】pixiPowerful system-level package manager for Linux, macOS and Windows written in Rust – building on top of the Conda ecosystem.项目地址https://gitcode.com/gh_mirrors/pi/pixi点击查看免费下载相关推荐Pixi 构建后端 pixi-build-rust用 Cargo 自动生成 Conda 包Pixi 构建后端 pixi build rust用 Cargo 自动生成 Conda 包 pixi build rust 是 Pixi 的 Rust 项目构开发工具CLI包管理器任务调度Escrcpy 安卓屏幕镜像到电脑完整指南3 分钟 USB 投屏 无线配对步骤教程Escrcpy 安卓屏幕镜像到电脑完整指南3 分钟 USB 投屏 无线配对步骤教程 Escrcpy 是一款基于 scrcpyAndroid 屏幕投射与操开发工具CLI包管理器任务调度使用 Pixi 的 build 功能从源码构建 conda 包Manifest 配置、后端机制与发布实战使用 Pixi 的 build 功能从源码构建 conda 包Manifest 配置、后端机制与发布实战 Pixi 不仅能管理工作流与环境还能直接从源码构建开发工具CLI包管理器任务调度上一篇Rust桌面应用Tauri框架与跨平台GUI下一篇BiliDrive安全机制详解META URL如何保障你的文件不被他人访问创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考