XGBoost Python 包打包详解构建二进制 Wheel 与源码发行版sdist【免费下载链接】xgboostScalable, Portable and Distributed Gradient Boosting (GBDT, GBRT or GBM) Library, for Python, R, Java, Scala, C and more. Runs on single machine, Hadoop, Spark, Dask, Flink and DataFlow项目地址: https://gitcode.com/gh_mirrors/xg/xgboost本文基于仓库中的 doc/contrib/python_packaging.rst 展开系统讲解 XGBoost Python 包两种标准分发形态——源码发行版sdist与二进制 wheel——的构建方法、产物差异与底层原理。读完后你将能够自行构建可分发的 XGBoost 包并理解其中 CMake 构建后端、共享库打包与运行时库查找机制的完整链路。两种分发机制sdist 与 wheelWheel 和源码发行版source distribution简称 sdist是打包和分发 Python 包的两种主要机制源码发行版sdist一个 tarball.tar.gz扩展名包含源码。wheel一个 ZIP 压缩归档.whl扩展名代表一个已构建的发行版。与 sdist 不同wheel 可以包含编译产物。编译产物在分发前已完成编译对终端用户而言安装 wheel 更方便。包含编译产物的 wheel 称为二进制 wheelbinary wheel。理解这两种形态的关键差异在于wheel 是构建完成的产物sdist 是构建原料的产物。对 XGBoost 这样的 C 核心 Python 绑定项目这一差异直接体现在是否需要在pip install时现场编译上。构建源码发行版sdist对 XGBoost 而言sdist 同时包含 Python 代码和 C 代码因此 XGBoost 的核心部分可以被编译成共享库libxgboost.so不同操作系统下共享库文件名不同见结尾脚注。你可以用如下命令获得 sdist$ python -m build --sdist .执行前需要先安装build包pip install build或conda install python-build。用 sdist 执行pip install会启动 CMake 和 C 编译器把捆绑的 C 代码编译为libxgboost.so$ pip install -v xgboost-2.0.0.tar.gz # 加 -v 可查看构建进度仓库源码视角sdist 如何做到自包含上面的python -m build --sdist .在当前仓库结构下应在 python-package/ 目录中执行该目录下的 pyproject.toml 声明了构建系统。这里有一个值得注意的工程细节sdist 需要把仓库根目录的整个 C 源码树塞进发行版但构建后端的打包规则只能看到项目根目录之下的文件。仓库用一个独立脚本来解决这一点即 ops/script/prepare_sdist.py它把src、include、dmlc-core、cmake、plugin五个 C 子目录连同根目录的CMakeLists.txt和LICENSE整体拷贝到python-package/cpp_src/暂存目录脚本是幂等的每次运行先清空并重建暂存目录它必须在python -m build --sdist之前运行。pyproject.toml 中的相应配置印证了这一流程[tool.scikit-build] # Source distributions ship the C tree under cpp_src/, staged by # ops/script/prepare_sdist.py before python -m build --sdist. sdist.include [cpp_src/**] sdist.exclude [build/, dist/, wheelhouse/, *.pyc, __pycache__] sdist.reproducible true其中sdist.reproducible true开启可复现构建归档内文件时间戳等元数据归一化保证同一版本多次打出的 sdist 字节一致便于校验与审计。CI 中完整的 sdist 验证流程可见 ops/pipeline/test-python-sdist.sh先运行prepare_sdist.py暂存 C 源码树再进入python-package/执行python -m build --sdist随后用pip install -v ./dist/xgboost-*.tar.gz从 sdist 现场编译安装最后以python -c import xgboost确认导入成功。脚本中还演示了通过--config-settings cmake.define.CMAKE_C_COMPILER_LAUNCHERsccache给 CMake 注入编译缓存加速器的用法。构建二进制 wheel你也可以构建 wheel$ pip wheel --no-deps -v .--no-deps表示不连带构建/下载依赖。需要特别指出的是产物 wheel 中包含一份共享库libxgboost.so的拷贝。由于含有编译二进制这是一个二进制 wheel。用二进制 wheel 执行pip install时pip 只把 wheel 内容解压到当前 Python 环境。由于 wheel 内已经带有预构建的libxgboost.so安装时无需再构建因此pip install一个二进制 wheel 能很快完成$ pip install xgboost-2.0.0-py3-none-linux_x86_64.whl # 快速完成文件名中的版本号、Python ABI 标签与平台标签是 wheel 命名规范的一部分py3-none-linux_x86_64表示纯 Python 3 兼容、无特定 C 扩展 ABI、面向 Linux x86_64。仓库源码视角wheel 中的 libxgboost 从何而来Python 侧的构建入口是 python-package/CMakeLists.txt它支持两种构建模式复用预构建库如果${C 源码}/lib/目录下已存在libxgboost.{so,dylib,dll}通常由 CI 先在仓库根用 CMake 构建好则直接把该库安装进 wheel 的xgboost/lib/目录。源码中还专门处理了 SOVERSION 符号链接.so - .so.3 - .so.3.3.0的情况——先file(REAL_PATH ...)解析到底层实体文件再安装避免 wheel 打包器丢弃悬空软链。从源码编译如果没有预构建库例如pip install python-package/或从 sdist 安装的场景该 CMakeLists 通过add_subdirectory()挂载 C 源码树现场编译。sdist 安装时 C 树位于本文件旁边的cpp_src/由prepare_sdist.py暂存仓库内构建时则指向父目录。两种路径最终都把共享库以无版本号的文件名安装为xgboost/lib/下的libxgboost.so或对应平台名这正是 Python 端加载器期望的位置。pyproject.toml中与 wheel 构建直接相关的配置[build-system] requires [scikit-build-core0.11.0] build-backend scikit_build_core.build [tool.scikit-build] build-dir build/{wheel_tag} ninja.make-fallback true wheel.py-api py3 wheel.packages [xgboost] # Only install rules tagged with COMPONENT XGBoostPython make it into the # wheel. C subprojects (e.g. dmlc-core) register their own install() rules # for headers / static libs / CMake configs that we dont want inside the # Python wheel; this filter quietly skips all of them. install.components [XGBoostPython] [tool.scikit-build.cmake] version CMakeLists.txt build-type Release几个关键点构建后端是scikit-build-core它驱动 CMake 完成 C 编译并组装 wheelbuild-type Release指定优化编译install.components [XGBoostPython]是一个过滤器只有带该 COMPONENT 标签的安装规则才会进入 wheel从而把 dmlc-core 等 C 子项目面向系统安装的 headers/静态库/CMake 配置规则全部排除在外ninja.make-fallback true允许在没有 Ninja 时回退到 Makefile 生成器。另外pyproject.toml 文件头注明其由 ops/script/pypi_variants.py 自动生成当前变体为--use-suffixna --require-nccl-depcu13用于派生不同发行渠道所需的依赖组合——例如 CUDA 13 变体在 Linux 上额外声明nvidia-nccl-cu13运行时依赖。CI 中对 wheel 的验证CI 的 wheel 测试脚本 ops/pipeline/test-python-wheel.sh 演示了官方对 wheel 产物的验收方式安装./wheelhouse/*.whl后对于 GPU 变体会调用from xgboost import build_info读取build_info()[CUDA_VERSION]断言 wheel 实际是用预期大版本的 CUDA 构建的再按 CPU/GPU/多 GPU/ARM64 等套件分别运行对应测试集。这为二进制 wheel 必须与宣传的构建环境一致提供了可执行的验证手段。运行时如何找到共享库为什么 wheel 必须把libxgboost.so打进xgboost/lib/答案在 python-package/xgboost/libpath.py 的find_lib_path()首先找包内的xgboost/lib/normal, after installationlibis copied into Python package tree——这对应 wheel 安装的场景库就内置在包目录里其次找仓库布局下的../../lib/editable 安装时不做拷贝最后回退到系统前缀sys.base_prefix/lib并在 Windows 上追加若干 Conda 目录找不到时抛出XGBoostLibraryNotFound错误信息中列出所有候选路径以便排查。文件名也是按平台硬编码映射的Linux/FreeBSD/Emscripten 为libxgboost.somacOS 为libxgboost.dylibWindows 为xgboost.dllCygwin 为cygxgboost.dll。这与 python-package/CMakeLists.txt 中_XGB_LIBNAME的平台分支一一对应。相关配置速查主题位置说明构建后端声明python-package/pyproject.tomlscikit-build-core0.11.0sdist.include [cpp_src/**]C 树暂存ops/script/prepare_sdist.py打 sdist 前把src/include/dmlc-core/cmake/plugin拷入python-package/cpp_src/wheel 打包 CMakepython-package/CMakeLists.txt预构建库复用 / 源码编译两种模式sdist CI 验证ops/pipeline/test-python-sdist.shsdist 构建 现场编译安装 import xgboost冒烟wheel CI 验证ops/pipeline/test-python-wheel.sh安装 wheel 并核对build_info()的 CUDA 版本运行时库查找python-package/xgboost/libpath.py按平台解析共享库名与候选路径共享库构建文档doc/build.rstCMake 选项USE_CUDA、USE_NCCL等与平台库名共享库文件名的平台差异脚注继承原文档共享库文件名会随操作系统变化——Linux 及其他类 UNIX 系统libxgboost.somacOSlibxgboost.dylibWindowsxgboost.dll完整的共享库构建说明参见仓库文档 doc/build.rst 中 Building the Shared Library 一节即原文档脚注引用的build_shared_lib锚点其中还给出了 GPUUSE_CUDA、NCCLUSE_NCCL、USE_DLOPEN_NCCL、HIDE_CXX_SYMBOLS等常用 CMake 选项。小结sdist 是源码 构建配方pip install时由 CMake 现场编译libxgboost.so适合无法提供 wheel 的目标平台代价是安装慢、要求本机有 C 工具链二进制 wheel 内置预编译的libxgboost.so安装到xgboost/lib/pip install秒级完成是终端用户的首选两条链路的公共基石是 python-package/ 下由 scikit-build-core 驱动的 CMake 构建配合install.components [XGBoostPython]过滤确保 wheel 内容精确可控复现 CI 行为时参考 ops/pipeline/test-python-sdist.sh 与 ops/pipeline/test-python-wheel.sh 中的命令序列即可。【免费下载链接】xgboostScalable, Portable and Distributed Gradient Boosting (GBDT, GBRT or GBM) Library, for Python, R, Java, Scala, C and more. Runs on single machine, Hadoop, Spark, Dask, Flink and DataFlow项目地址: https://gitcode.com/gh_mirrors/xg/xgboost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 XGBoost Python 包打包详解：构建二进制 Wheel 与源码发行版（sdist）
XGBoost Python 包打包详解构建二进制 Wheel 与源码发行版sdist【免费下载链接】xgboostScalable, Portable and Distributed Gradient Boosting (GBDT, GBRT or GBM) Library, for Python, R, Java, Scala, C and more. Runs on single machine, Hadoop, Spark, Dask, Flink and DataFlow项目地址: https://gitcode.com/gh_mirrors/xg/xgboost本文基于仓库中的 doc/contrib/python_packaging.rst 展开系统讲解 XGBoost Python 包两种标准分发形态——源码发行版sdist与二进制 wheel——的构建方法、产物差异与底层原理。读完后你将能够自行构建可分发的 XGBoost 包并理解其中 CMake 构建后端、共享库打包与运行时库查找机制的完整链路。两种分发机制sdist 与 wheelWheel 和源码发行版source distribution简称 sdist是打包和分发 Python 包的两种主要机制源码发行版sdist一个 tarball.tar.gz扩展名包含源码。wheel一个 ZIP 压缩归档.whl扩展名代表一个已构建的发行版。与 sdist 不同wheel 可以包含编译产物。编译产物在分发前已完成编译对终端用户而言安装 wheel 更方便。包含编译产物的 wheel 称为二进制 wheelbinary wheel。理解这两种形态的关键差异在于wheel 是构建完成的产物sdist 是构建原料的产物。对 XGBoost 这样的 C 核心 Python 绑定项目这一差异直接体现在是否需要在pip install时现场编译上。构建源码发行版sdist对 XGBoost 而言sdist 同时包含 Python 代码和 C 代码因此 XGBoost 的核心部分可以被编译成共享库libxgboost.so不同操作系统下共享库文件名不同见结尾脚注。你可以用如下命令获得 sdist$ python -m build --sdist .执行前需要先安装build包pip install build或conda install python-build。用 sdist 执行pip install会启动 CMake 和 C 编译器把捆绑的 C 代码编译为libxgboost.so$ pip install -v xgboost-2.0.0.tar.gz # 加 -v 可查看构建进度仓库源码视角sdist 如何做到自包含上面的python -m build --sdist .在当前仓库结构下应在 python-package/ 目录中执行该目录下的 pyproject.toml 声明了构建系统。这里有一个值得注意的工程细节sdist 需要把仓库根目录的整个 C 源码树塞进发行版但构建后端的打包规则只能看到项目根目录之下的文件。仓库用一个独立脚本来解决这一点即 ops/script/prepare_sdist.py它把src、include、dmlc-core、cmake、plugin五个 C 子目录连同根目录的CMakeLists.txt和LICENSE整体拷贝到python-package/cpp_src/暂存目录脚本是幂等的每次运行先清空并重建暂存目录它必须在python -m build --sdist之前运行。pyproject.toml 中的相应配置印证了这一流程[tool.scikit-build] # Source distributions ship the C tree under cpp_src/, staged by # ops/script/prepare_sdist.py before python -m build --sdist. sdist.include [cpp_src/**] sdist.exclude [build/, dist/, wheelhouse/, *.pyc, __pycache__] sdist.reproducible true其中sdist.reproducible true开启可复现构建归档内文件时间戳等元数据归一化保证同一版本多次打出的 sdist 字节一致便于校验与审计。CI 中完整的 sdist 验证流程可见 ops/pipeline/test-python-sdist.sh先运行prepare_sdist.py暂存 C 源码树再进入python-package/执行python -m build --sdist随后用pip install -v ./dist/xgboost-*.tar.gz从 sdist 现场编译安装最后以python -c import xgboost确认导入成功。脚本中还演示了通过--config-settings cmake.define.CMAKE_C_COMPILER_LAUNCHERsccache给 CMake 注入编译缓存加速器的用法。构建二进制 wheel你也可以构建 wheel$ pip wheel --no-deps -v .--no-deps表示不连带构建/下载依赖。需要特别指出的是产物 wheel 中包含一份共享库libxgboost.so的拷贝。由于含有编译二进制这是一个二进制 wheel。用二进制 wheel 执行pip install时pip 只把 wheel 内容解压到当前 Python 环境。由于 wheel 内已经带有预构建的libxgboost.so安装时无需再构建因此pip install一个二进制 wheel 能很快完成$ pip install xgboost-2.0.0-py3-none-linux_x86_64.whl # 快速完成文件名中的版本号、Python ABI 标签与平台标签是 wheel 命名规范的一部分py3-none-linux_x86_64表示纯 Python 3 兼容、无特定 C 扩展 ABI、面向 Linux x86_64。仓库源码视角wheel 中的 libxgboost 从何而来Python 侧的构建入口是 python-package/CMakeLists.txt它支持两种构建模式复用预构建库如果${C 源码}/lib/目录下已存在libxgboost.{so,dylib,dll}通常由 CI 先在仓库根用 CMake 构建好则直接把该库安装进 wheel 的xgboost/lib/目录。源码中还专门处理了 SOVERSION 符号链接.so - .so.3 - .so.3.3.0的情况——先file(REAL_PATH ...)解析到底层实体文件再安装避免 wheel 打包器丢弃悬空软链。从源码编译如果没有预构建库例如pip install python-package/或从 sdist 安装的场景该 CMakeLists 通过add_subdirectory()挂载 C 源码树现场编译。sdist 安装时 C 树位于本文件旁边的cpp_src/由prepare_sdist.py暂存仓库内构建时则指向父目录。两种路径最终都把共享库以无版本号的文件名安装为xgboost/lib/下的libxgboost.so或对应平台名这正是 Python 端加载器期望的位置。pyproject.toml中与 wheel 构建直接相关的配置[build-system] requires [scikit-build-core0.11.0] build-backend scikit_build_core.build [tool.scikit-build] build-dir build/{wheel_tag} ninja.make-fallback true wheel.py-api py3 wheel.packages [xgboost] # Only install rules tagged with COMPONENT XGBoostPython make it into the # wheel. C subprojects (e.g. dmlc-core) register their own install() rules # for headers / static libs / CMake configs that we dont want inside the # Python wheel; this filter quietly skips all of them. install.components [XGBoostPython] [tool.scikit-build.cmake] version CMakeLists.txt build-type Release几个关键点构建后端是scikit-build-core它驱动 CMake 完成 C 编译并组装 wheelbuild-type Release指定优化编译install.components [XGBoostPython]是一个过滤器只有带该 COMPONENT 标签的安装规则才会进入 wheel从而把 dmlc-core 等 C 子项目面向系统安装的 headers/静态库/CMake 配置规则全部排除在外ninja.make-fallback true允许在没有 Ninja 时回退到 Makefile 生成器。另外pyproject.toml 文件头注明其由 ops/script/pypi_variants.py 自动生成当前变体为--use-suffixna --require-nccl-depcu13用于派生不同发行渠道所需的依赖组合——例如 CUDA 13 变体在 Linux 上额外声明nvidia-nccl-cu13运行时依赖。CI 中对 wheel 的验证CI 的 wheel 测试脚本 ops/pipeline/test-python-wheel.sh 演示了官方对 wheel 产物的验收方式安装./wheelhouse/*.whl后对于 GPU 变体会调用from xgboost import build_info读取build_info()[CUDA_VERSION]断言 wheel 实际是用预期大版本的 CUDA 构建的再按 CPU/GPU/多 GPU/ARM64 等套件分别运行对应测试集。这为二进制 wheel 必须与宣传的构建环境一致提供了可执行的验证手段。运行时如何找到共享库为什么 wheel 必须把libxgboost.so打进xgboost/lib/答案在 python-package/xgboost/libpath.py 的find_lib_path()首先找包内的xgboost/lib/normal, after installationlibis copied into Python package tree——这对应 wheel 安装的场景库就内置在包目录里其次找仓库布局下的../../lib/editable 安装时不做拷贝最后回退到系统前缀sys.base_prefix/lib并在 Windows 上追加若干 Conda 目录找不到时抛出XGBoostLibraryNotFound错误信息中列出所有候选路径以便排查。文件名也是按平台硬编码映射的Linux/FreeBSD/Emscripten 为libxgboost.somacOS 为libxgboost.dylibWindows 为xgboost.dllCygwin 为cygxgboost.dll。这与 python-package/CMakeLists.txt 中_XGB_LIBNAME的平台分支一一对应。相关配置速查主题位置说明构建后端声明python-package/pyproject.tomlscikit-build-core0.11.0sdist.include [cpp_src/**]C 树暂存ops/script/prepare_sdist.py打 sdist 前把src/include/dmlc-core/cmake/plugin拷入python-package/cpp_src/wheel 打包 CMakepython-package/CMakeLists.txt预构建库复用 / 源码编译两种模式sdist CI 验证ops/pipeline/test-python-sdist.shsdist 构建 现场编译安装 import xgboost冒烟wheel CI 验证ops/pipeline/test-python-wheel.sh安装 wheel 并核对build_info()的 CUDA 版本运行时库查找python-package/xgboost/libpath.py按平台解析共享库名与候选路径共享库构建文档doc/build.rstCMake 选项USE_CUDA、USE_NCCL等与平台库名共享库文件名的平台差异脚注继承原文档共享库文件名会随操作系统变化——Linux 及其他类 UNIX 系统libxgboost.somacOSlibxgboost.dylibWindowsxgboost.dll完整的共享库构建说明参见仓库文档 doc/build.rst 中 Building the Shared Library 一节即原文档脚注引用的build_shared_lib锚点其中还给出了 GPUUSE_CUDA、NCCLUSE_NCCL、USE_DLOPEN_NCCL、HIDE_CXX_SYMBOLS等常用 CMake 选项。小结sdist 是源码 构建配方pip install时由 CMake 现场编译libxgboost.so适合无法提供 wheel 的目标平台代价是安装慢、要求本机有 C 工具链二进制 wheel 内置预编译的libxgboost.so安装到xgboost/lib/pip install秒级完成是终端用户的首选两条链路的公共基石是 python-package/ 下由 scikit-build-core 驱动的 CMake 构建配合install.components [XGBoostPython]过滤确保 wheel 内容精确可控复现 CI 行为时参考 ops/pipeline/test-python-sdist.sh 与 ops/pipeline/test-python-wheel.sh 中的命令序列即可。【免费下载链接】xgboostScalable, Portable and Distributed Gradient Boosting (GBDT, GBRT or GBM) Library, for Python, R, Java, Scala, C and more. Runs on single machine, Hadoop, Spark, Dask, Flink and DataFlow项目地址: https://gitcode.com/gh_mirrors/xg/xgboost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考