从源代码构建

本页面提供了在各种系统上从源代码构建和安装 XGBoost 的说明。如果这些说明不适合您，请随时在 GitHub 上提问。

注意

提供预构建二进制文件：现支持 GPU

考虑从预构建二进制文件安装 XGBoost，以避免从源代码构建的麻烦。请查看安装指南。

获取源代码

要获取 XGBoost 的开发仓库，需要使用 git。XGBoost 使用 Git 子模块管理依赖项。因此，克隆仓库时，请记住指定 --recursive 选项

git clone --recursive https://github.com/dmlc/xgboost

构建共享库

本节介绍了独立构建共享库和 CLI 接口的步骤。要构建特定语言的包，请参阅本文档中相应的章节。

  • 在 Linux 和其他类 UNIX 系统上，目标库是 libxgboost.so

  • 在 MacOS 上，目标库是 libxgboost.dylib

  • 在 Windows 上，目标库是 xgboost.dll

这个共享库被不同的语言绑定使用（根据您选择的绑定可能会有一些额外内容）。最低构建要求是

  • 一个支持 C++17 的最新 C++ 编译器。我们日常测试使用 gcc、clang 和 MSVC。Mingw 仅用于 R 包且功能有限。

  • CMake 3.18 或更高版本。

有关 GPU 支持等 CMake 选项列表，请参阅源代码树顶层 CMakeLists.txt 中的 #-- Options。本文档中我们使用 ninja 进行构建，通过 CMake 标志 -GNinja 指定。如果您偏好其他构建工具，如 make 或 Visual Studio 17 2022，请修改相应的 CMake 标志。需要时请查阅 CMake 生成器 文档。

运行 CMake 并构建

获取源代码后，通过运行 CMake 构建 XGBoost

cd xgboost
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo -GNinja
cd build && ninja

该命令适用于类 Unix 系统和 Windows。运行构建后，应在 xgboost/lib 目录下看到一个共享对象。

  • 在 MacOS 上构建

    在 MacOS 上，需要先从 Homebrew 获取 libomp

    brew install libomp

  • Visual Studio

    最新版本的 Visual Studio 内置支持 CMake 项目。如果您更喜欢使用 IDE 而不是命令行，可以在 xgboost 源代码目录下的右键菜单中使用 open with visual studio 选项。有关更多信息，请查阅 VS 文档。

构建并支持 GPU

XGBoost 可以使用 CMake 在 Linux 和 Windows 上构建并支持 GPU。有关 R 的特殊说明，请参阅构建支持 GPU 的 R 包。

需要安装最新版本的 CUDA 工具包。

注意

检查编译器版本

CUDA 对支持的编译器非常挑剔，可以在此处查看 Linux 上最新 CUDA 版本兼容的编译器表格。

一些发行版会随 CUDA 一起打包兼容的 gcc 版本。如果使用 nvcc 遇到编译器错误，请尝试使用 -DCMAKE_CXX_COMPILER=/path/to/correct/g++ -DCMAKE_C_COMPILER=/path/to/correct/gcc 指定正确的编译器。例如，在 Arch Linux 上，这两个二进制文件都可以在 /opt/cuda/bin/ 下找到。此外，CMAKE_CUDA_HOST_COMPILER 参数也可能有用。

在 Linux 命令行中，从 XGBoost 目录开始，添加 USE_CUDA 标志

cmake -B build -S . -DUSE_CUDA=ON -GNinja
cd build && ninja

为了加快编译速度，可以将特定于您的 GPU 的计算版本传递给 cmake，例如 -DCMAKE_CUDA_ARCHITECTURES=75。可以在此页面上找到一些架构的快速解释和编号。

  • 使用 NCCL 加快分布式 GPU 训练

    默认情况下，分布式 GPU 训练通过选项 USE_NCCL=ON 启用。分布式 GPU 训练依赖于 NCCL2，可在此链接获取。由于 NCCL2 仅适用于 Linux 机器，因此 分布式 GPU 训练仅适用于 Linux。

    cmake -B build -S . -DUSE_CUDA=ON -DUSE_NCCL=ON -DNCCL_ROOT=/path/to/nccl2 -GNinja
cd build && ninja

    NCCL 还有一些附加标志可用，BUILD_WITH_SHARED_NCCL 允许将 NCCL 构建为共享库，而 USE_DLOPEN_NCCL 允许 XGBoost 在运行时使用 dlopen 加载 NCCL。

联邦学习

联邦学习插件需要 grpc 和 protobuf。要安装 grpc，请参阅 gRPC 网站上的安装指南。或者，如果安装了 conda，可以使用 conda forge 中的 libgrpc 和 protobuf 包。获取所需依赖项后，在运行 CMake 时启用标志：-DPLUGIN_FEDERATED=ON。请注意，联邦插件仅支持 Linux。

cmake -B build -S . -DPLUGIN_FEDERATED=ON -GNinja
cd build && ninja

从源代码构建 Python 包

Python 包位于 python-package/。

使用默认工具链构建 Python 包

有几种方法可以从源代码构建和安装该包

  1. 先使用 CMake 构建 C++ 核心

您可以首先使用 CMake 构建 C++ 库，如构建共享库所述。编译后，将在 lib/ 目录中出现一个共享库。在 Linux 发行版上，共享库是 lib/libxgboost.so。安装脚本 pip install . 将重复使用该共享库，而不是从头编译，这使得运行速度非常快。

$ cd python-package/
$ pip install .  # Will re-use lib/libxgboost.so

  1. 直接安装 Python 包

如果共享对象不存在，Python 项目设置脚本将尝试自动运行 CMake 构建命令。导航到 python-package/ 目录，然后运行以下命令安装 Python 包

$ cd python-package/
$ pip install -v . # Builds the shared object automatically.

这将使用默认的 CMake 标志编译 XGBoost 的原生 (C++) 代码。要启用其他编译选项，请传递相应的 --config-settings

$ pip install -v . --config-settings use_cuda=True --config-settings use_nccl=True

请使用 Pip 22.1 或更高版本才能使用 --config-settings 选项。

以下是 --config-settings 的可用选项

@dataclasses.dataclass
class BuildConfiguration:  # pylint: disable=R0902
    """Configurations use when building libxgboost"""

    # Whether to hide C++ symbols in libxgboost.so
    hide_cxx_symbols: bool = True
    # Whether to enable OpenMP
    use_openmp: bool = True
    # Whether to enable CUDA
    use_cuda: bool = False
    # Whether to enable NCCL
    use_nccl: bool = False
    # Whether to load nccl dynamically
    use_dlopen_nccl: bool = False
    # Whether to enable federated learning
    plugin_federated: bool = False
    # Whether to enable rmm support
    plugin_rmm: bool = False
    # Special option: See explanation below
    use_system_libxgboost: bool = False

use_system_libxgboost 是一个特殊选项。有关详细说明，请参阅下面的第 4 项。

注意

建议使用详细输出标志

由于 pip install . 会构建 C++ 代码，这将需要一些时间才能完成。为确保构建顺利进行，我们建议您在调用 pip install 时添加详细输出标志 (-v)。

  1. 可编辑安装

为了进一步实现快速开发和迭代，我们提供了可编辑安装。在可编辑安装中，安装的包只是指向您 XGBoost 源代码工作副本的符号链接。因此，您对源代码目录所做的任何更改都会立即对 Python 解释器可见。要以可编辑安装方式安装 XGBoost，请首先按照运行 CMake 并构建中先前描述的方式构建共享库，然后使用 -e 标志安装 Python 包

# Build shared library libxgboost.so
cmake -B build -S . -GNinja
cd build && ninja
# Install as editable installation
cd ../python-package
pip install -e .

  1. 重用系统路径上的 libxgboost.so。

此选项对于希望单独打包 libxgboost.so 和 XGBoost Python 包的包管理器非常有用。例如，Conda 发布 libxgboost（用于共享库）和 py-xgboost（用于 Python 包）。

要使用此选项，请首先确保 libxgboost.so 存在于系统库路径中

import sys
import pathlib
libpath = pathlib.Path(sys.base_prefix).joinpath("lib", "libxgboost.so")
assert libpath.exists()

然后将 use_system_libxgboost=True 选项传递给 pip install

cd python-package
pip install . --config-settings use_system_libxgboost=True

注意

有关将 XGBoost 打包和分发为 Python 发行版的说明，请参阅关于打包 XGBoost Python 包的说明。

从源代码构建 R 包

默认情况下，通过运行 install.packages 安装的包是使用 CRAN 中的包从源代码构建的。这里我们列出了安装开发版本的其他一些选项。

安装开发版本 (Linux / Mac OSX)

请确保您已安装 git 和支持 C++11 的最新 C++ 编译器（有关构建 C++ 核心的要求，请参阅以上章节）。

由于使用了 git 子模块，remotes::install_github() 不能用于安装最新版本的 R 包。因此，必须先运行 git 检出代码，请参阅获取源代码了解如何初始化 XGBoost 的 git 仓库。获取源代码后安装 R 包的最简单方法是

cd R-package
R CMD INSTALL .

如果您想加快构建速度，请使用环境变量 MAKEFLAGS=-j$(nproc)。另一种方法是，也可以从仓库根目录下的同一个子文件夹 R-package 中通过 devtools::load_all() 加载包，并且如果将该文件夹 R-package 作为 RStudio IDE 中的 R 包项目添加，则可以通过 RStudio 的构建面板进行安装。

library(devtools)
devtools::load_all(path = "/path/to/xgboost/R-package")

在 Linux 上，如果您想使用 CMake 构建以获得更大的编译标志灵活性，可以将前面的代码片段替换为

cmake -B build -S . -DR_LIB=ON -GNinja
cd build && ninja install

警告

MSVC 不支持 R 包，因为它难以处理 R 的 C 头文件。CMake 构建也不支持。

请注意，在这种情况下，cmake 不会从您的常规 Makevars 文件（如果您在 ~/.R/Makevars 下有此文件）中读取配置 - 相反，自定义配置（如要使用的编译器和标志）需要通过 CMake 变量（如 -DCMAKE_CXX_COMPILER）设置。

构建支持 GPU 的 R 包

步骤和要求与构建并支持 GPU类似，因此请务必先阅读它。

在 Linux 上，从 XGBoost 目录开始输入

cmake -B build -S . -DUSE_CUDA=ON -DR_LIB=ON
cmake --build build --target install -j$(nproc)

使用默认目标时，R 包共享库将在 build 区域构建。此外，install 目标会将包文件与此共享库一起组装到 build/R-package 下并运行 R CMD INSTALL。

构建 JVM 包

使用 Maven 构建 XGBoost4J 需要 Maven 3 或更高版本、Java 7+ 和 CMake 3.18+，用于编译 Java 代码以及 Java 本地接口 (JNI) 绑定。此外，配置期间会使用 Python 脚本，请确保系统路径中提供了 python 命令（有些发行版使用 python3 名称而不是 python）。

在安装 XGBoost4J 之前，您需要将环境变量 JAVA_HOME 定义为您的 JDK 目录，以确保编译器能够正确找到 jni.h，因为 XGBoost4J 依赖 JNI 实现 JVM 和原生库之间的交互。

正确定义 JAVA_HOME 后，只需在 jvm-packages 目录下运行 mvn package 即可安装 XGBoost4J。如果您确定本地设置正确，也可以通过运行 mvn -DskipTests=true package 跳过测试。

要将构建产物发布到本地 maven 仓库，请运行

mvn install

或者，如果您想跳过测试，请运行

mvn -DskipTests install

此命令会将 xgboost 二进制文件、编译后的 java 类以及 java 源代码发布到您的本地仓库。然后，您可以在 Java 项目中通过在 pom.xml 中包含以下依赖项来使用 XGBoost4J

<dependency>
  <groupId>ml.dmlc</groupId>
  <artifactId>xgboost4j</artifactId>
  <version>latest_source_version_num</version>
</dependency>

对于 sbt，请在 build.sbt 中添加仓库和依赖项，如下所示

resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/repository"

"ml.dmlc" % "xgboost4j" % "latest_source_version_num"

如果要使用 XGBoost4J-Spark，请将 xgboost4j 替换为 xgboost4j-spark。

注意

XGBoost4J-Spark 需要 Apache Spark 2.3+

XGBoost4J-Spark 现在需要 Apache Spark 3.4+。最新版本的 XGBoost4J-Spark 广泛使用了 org.apache.spark.ml.param.shared 的功能，以提供与 Spark MLLIB 框架的紧密集成，而这些功能在早期版本的 Spark 中并未完全可用。

此外，请务必直接从 Apache 网站安装 Spark。无法保证上游 XGBoost 与第三方 Spark 发行版（例如 Cloudera Spark）兼容。请咨询相应的第三方以获取其 XGBoost 发行版。

附加系统相关特性

  • MacOS 上的 OpenMP：请参阅运行 CMake 并构建安装 openmp。可以使用标志 -Duse.openmp=OFF 禁用 OpenMP 支持。

  • 通过向 maven 传递附加标志 mvn -Duse.cuda=ON install 可以启用 GPU 支持。有关更多信息，请参阅构建并支持 GPU。此外，-Dplugin.rmm=ON 可以启用可选的 RMM 支持。

构建文档

XGBoost 使用 Sphinx 生成文档。要在本地构建它，您需要安装 XGBoost 及其所有依赖项，以及

  • 系统依赖项

    • git

    • graphviz

  • Python 依赖项

    查阅 doc/ 下的 requirements.txt 文件

在 xgboost/doc 目录下，运行 make <format>，将 <format> 替换为您想要的格式。要查看支持的格式列表，请在同一目录下运行 make help。这将构建 Python 的部分文档，但不包括其他语言绑定。要构建完整文档，请参阅文档和示例。