Running CMake and build

After obtaining the source code, one builds XGBoost by running CMake:

cdxgboostcmake-Bbuild-S.-DCMAKE_BUILD_TYPE=RelWithDebInfo-GNinjacdbuild&&ninja

The same command applies for both Unix-like systems and Windows. After running thebuild, one should see a shared object under thexgboost/lib directory.

• Building on MacOS

  On MacOS, one needs to obtainlibomp fromHomebrew first:

  brewinstalllibomp

• Visual Studio

  The latest Visual Studio has builtin support for CMake projects. If you prefer using anIDE over the command line, you can use theopenwithvisualstudio option in theright-click menu under thexgboost source directory. Consult the VSdocumentfor more info.

Building with GPU support

XGBoost can be built with GPU support for both Linux and Windows using CMake. SeeBuilding R package with GPU support for special instructions for R.

An up-to-date version of the CUDA toolkit is required.

Some distros package a compatiblegcc version with CUDA. If you run into compilererrors withnvcc, try specifying the correct compiler with-DCMAKE_CXX_COMPILER=/path/to/correct/g++-DCMAKE_C_COMPILER=/path/to/correct/gcc. OnArch Linux, for example, both binaries can be found under/opt/cuda/bin/. In addition,theCMAKE_CUDA_HOST_COMPILER parameter can be useful.

From the command line on Linux starting from the XGBoost directory, add theUSE_CUDAflag:

cmake-Bbuild-S.-DUSE_CUDA=ON-GNinjacdbuild&&ninja

To speed up compilation, the compute version specific to your GPU could be passed to cmakeas, e.g.,-DCMAKE_CUDA_ARCHITECTURES=75. A quick explanation and numbers for somearchitectures can be foundin this page.

• Faster distributed GPU training with NCCL

  By default, distributed GPU training is enabled with the optionUSE_NCCL=ON. Distributed GPU training depends on NCCL2, available atthis link. Since NCCL2 is only available for Linux machines,Distributed GPU training is available only for Linux.

  cmake-Bbuild-S.-DUSE_CUDA=ON-DUSE_NCCL=ON-DNCCL_ROOT=/path/to/nccl2-GNinjacdbuild&&ninja

  Some additional flags are available for NCCL,BUILD_WITH_SHARED_NCCL enablesbuilding XGBoost with NCCL as a shared library, whileUSE_DLOPEN_NCCL enablesXGBoost to load NCCL at runtime usingdlopen.

Federated Learning

The federated learning plugin requiresgrpc andprotobuf. To install grpc, referto theinstallation guide from the gRPC website. Alternatively, one can use thelibgrpc and theprotobuf package from conda forge if conda is available. Afterobtaining the required dependencies, enable the flag:-DPLUGIN_FEDERATED=ON whenrunning CMake. Please note that only Linux is supported for the federated plugin.

cmake-Bbuild-S.-DPLUGIN_FEDERATED=ON-GNinjacdbuild&&ninja

Building Python Package with Default Toolchains

There are several ways to build and install the package from source:

1. Build C++ core with CMake first

You can first build C++ library using CMake as described inBuilding the Shared Library.After compilation, a shared library will appear inlib/ directory.On Linux distributions, the shared library islib/libxgboost.so.The install scriptpipinstall. will reuse the shared library instead of compilingit from scratch, making it quite fast to run.

$cdpython-package/$pipinstall.# Will re-use lib/libxgboost.so

2. Install the Python package directly

If the shared object is not present, the Python project setup script will try to run theCMake build command automatically. Navigate to thepython-package/ directory andinstall the Python package by running:

$cdpython-package/$pipinstall-v.# Builds the shared object automatically.

which will compile XGBoost’s native (C++) code using default CMake flags. To enableadditional compilation options, pass corresponding--config-settings:

$pipinstall-v.--config-settingsuse_cuda=True--config-settingsuse_nccl=True

Use Pip 22.1 or later to use--config-settings option.

Here are the available options for--config-settings:

@dataclasses.dataclassclassBuildConfiguration:# pylint: disable=R0902"""Configurations use when building libxgboost"""# Whether to hide C++ symbols in libxgboost.sohide_cxx_symbols:bool=True# Whether to enable OpenMPuse_openmp:bool=True# Whether to enable CUDAuse_cuda:bool=False# Whether to enable NCCLuse_nccl:bool=False# Whether to load nccl dynamicallyuse_dlopen_nccl:bool=False# Whether to enable federated learningplugin_federated:bool=False# Whether to enable rmm supportplugin_rmm:bool=False# Special option: See explanation belowuse_system_libxgboost:bool=False

use_system_libxgboost is a special option. See Item 4 below fordetailed description.

Note

Verbose flag recommended

Aspipinstall. will build C++ code, it will take a while to complete.To ensure that the build is progressing successfully, we suggest thatyou add the verbose flag (-v) when invokingpipinstall.

3. Editable installation

To further enable rapid development and iteration, we provide aneditableinstallation. In an editable installation, the installed package is simply a symboliclink to your working copy of the XGBoost source code. So every changes you make to yoursource directory will be immediately visible to the Python interpreter. To installXGBoost as editable installation, first build the shared library as previously describedinRunning CMake and build, then install the Python package with the-e flag:

# Build shared library libxgboost.socmake-Bbuild-S.-GNinjacdbuild&&ninja# Install as editable installationcd../python-packagepipinstall-e.

4. Reuse thelibxgboost.so on system path.

This option is useful for package managers that wish to separately packagelibxgboost.so and the XGBoost Python package. For example, Condapublisheslibxgboost (for the shared library) andpy-xgboost(for the Python package).

To use this option, first make sure thatlibxgboost.so exists in the system library path:

importsysimportpathliblibpath=pathlib.Path(sys.base_prefix).joinpath("lib","libxgboost.so")assertlibpath.exists()

Then passuse_system_libxgboost=True option topipinstall:

cdpython-packagepipinstall.--config-settingsuse_system_libxgboost=True

Installing the development version (Linux / Mac OSX)

Make sure you have installed git and a recent C++ compiler supporting C++11 (See abovesections for requirements of building C++ core).

Due to the use of git-submodules,remotes::install_github() cannot be used toinstall the latest version of R package. Thus, one has to run git to check out the codefirst, seeObtaining the Source Code on how to initialize the git repository for XGBoost. Thesimplest way to install the R package after obtaining the source code is:

cdR-packageRCMDINSTALL.

Use the environment variableMAKEFLAGS=-j$(nproc) if you want to speedup the build. Asan alternative, the package can also be loaded throughdevtools::load_all() from thesame subfolderR-package in the repository’s root, and by extension, can be installedthrough RStudio’s build panel if one adds that folderR-package as an R packageproject in the RStudio IDE.

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

On Linux, if you want to use the CMake build for greater flexibility around compile flags,the earlier snippet can be replaced by:

cmake-Bbuild-S.-DR_LIB=ON-GNinjacdbuild&&ninjainstall

Note in this case thatcmake will not take configurations from your regularMakevars file (if you have such a file under~/.R/Makevars) - instead, customconfigurations such as compilers to use and flags need to be set through CMake variableslike-DCMAKE_CXX_COMPILER.

Building R package with GPU support

The procedure and requirements are similar as inBuilding with GPU support, so make sure to read it first.

On Linux, starting from the XGBoost directory type:

cmake-Bbuild-S.-DUSE_CUDA=ON-DR_LIB=ONcmake--buildbuild--targetinstall-j$(nproc)

When default target is used, an R package shared library would be built in thebuild area.Theinstall target, in addition, assembles the package files with this shared library underbuild/R-package and runsRCMDINSTALL.

Additional System-dependent Features

• OpenMP on MacOS: SeeRunning CMake and build for installingopenmp. The flag-mvn-Duse.openmp=OFF can be used to disable OpenMP support.

• GPU support can be enabled by passing an additional flag to mavenmvn-Duse.cuda=ONinstall. SeeBuilding with GPU support for more info. In addition,-Dplugin.rmm=ONcan enable the optional RMM support.