1#################### 2Building From Source 3#################### 4 5This page gives instructions on how to build and install XGBoost from the source code on various 6systems. If the instructions do not work for you, please feel free to ask questions at 7`the user forum <https://discuss.xgboost.ai>`_. 8 9 10.. note:: Pre-built binary is available: now with GPU support 11 12 Consider installing XGBoost from a pre-built binary, to avoid the trouble of building XGBoost from the source. Checkout :doc:`Installation Guide </install>`. 13 14.. contents:: Contents 15 16************************* 17Obtaining the Source Code 18************************* 19To obtain the development repository of XGBoost, one needs to use ``git``. 20 21.. note:: Use of Git submodules 22 23 XGBoost uses Git submodules to manage dependencies. So when you clone the repo, remember to specify ``--recursive`` option: 24 25 .. code-block:: bash 26 27 git clone --recursive https://github.com/dmlc/xgboost 28 29For windows users who use github tools, you can open the git shell and type the following command: 30 31.. code-block:: batch 32 33 git submodule init 34 git submodule update 35 36 37.. _build_shared_lib: 38 39*************************** 40Building the Shared Library 41*************************** 42 43This section describes the procedure to build the shared library and CLI interface 44independently. For building language specific package, see corresponding sections in this 45document. 46 47- On Linux and other UNIX-like systems, the target library is ``libxgboost.so`` 48- On MacOS, the target library is ``libxgboost.dylib`` 49- On Windows the target library is ``xgboost.dll`` 50 51This shared library is used by different language bindings (with some additions depending 52on the binding you choose). The minimal building requirement is 53 54- A recent C++ compiler supporting C++11 (g++-5.0 or higher) 55- CMake 3.13 or higher. 56 57For a list of CMake options like GPU support, see ``#-- Options`` in CMakeLists.txt on top 58level of source tree. 59 60Building on Linux and other UNIX-like systems 61============================================= 62 63After obtaining the source code, one builds XGBoost by running CMake: 64 65.. code-block:: bash 66 67 cd xgboost 68 mkdir build 69 cd build 70 cmake .. 71 make -j$(nproc) 72 73Building on MacOS 74================= 75 76Obtain ``libomp`` from `Homebrew <https://brew.sh/>`_: 77 78.. code-block:: bash 79 80 brew install libomp 81 82 83Now clone the repository: 84 85.. code-block:: bash 86 87 git clone --recursive https://github.com/dmlc/xgboost 88 89Create the ``build/`` directory and invoke CMake. After invoking CMake, you can build XGBoost with ``make``: 90 91.. code-block:: bash 92 93 mkdir build 94 cd build 95 cmake .. 96 make -j4 97 98You may now continue to :ref:`build_python`. 99 100Building on Windows 101=================== 102You need to first clone the XGBoost repo with ``--recursive`` option, to clone the submodules. 103We recommend you use `Git for Windows <https://git-for-windows.github.io/>`_, as it comes with a standard Bash shell. This will highly ease the installation process. 104 105.. code-block:: bash 106 107 git submodule init 108 git submodule update 109 110XGBoost support compilation with Microsoft Visual Studio and MinGW. To build with Visual 111Studio, we will need CMake. Make sure to install a recent version of CMake. Then run the 112following from the root of the XGBoost directory: 113 114.. code-block:: bash 115 116 mkdir build 117 cd build 118 cmake .. -G"Visual Studio 14 2015 Win64" 119 # for VS15: cmake .. -G"Visual Studio 15 2017" -A x64 120 # for VS16: cmake .. -G"Visual Studio 16 2019" -A x64 121 cmake --build . --config Release 122 123This specifies an out of source build using the Visual Studio 64 bit generator. (Change the ``-G`` option appropriately if you have a different version of Visual Studio installed.) 124 125After the build process successfully ends, you will find a ``xgboost.dll`` library file 126inside ``./lib/`` folder. Some notes on using MinGW is added in :ref:`python_mingw`. 127 128.. _build_gpu_support: 129 130 131Building with GPU support 132========================= 133 134XGBoost can be built with GPU support for both Linux and Windows using CMake. See 135`Building R package with GPU support`_ for special instructions for R. 136 137An up-to-date version of the CUDA toolkit is required. 138 139.. note:: Checking your compiler version 140 141 CUDA is really picky about supported compilers, a table for the compatible compilers for the latests CUDA version on Linux can be seen `here <https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html>`_. 142 143 Some distros package a compatible ``gcc`` version with CUDA. If you run into compiler errors with ``nvcc``, try specifying the correct compiler with ``-DCMAKE_CXX_COMPILER=/path/to/correct/g++ -DCMAKE_C_COMPILER=/path/to/correct/gcc``. On Arch Linux, for example, both binaries can be found under ``/opt/cuda/bin/``. 144 145From the command line on Linux starting from the XGBoost directory: 146 147.. code-block:: bash 148 149 mkdir build 150 cd build 151 # For CUDA toolkit >= 11.4, `BUILD_WITH_CUDA_CUB` is required. 152 cmake .. -DUSE_CUDA=ON -DBUILD_WITH_CUDA_CUB=ON 153 make -j4 154 155.. note:: Specifying compute capability 156 157 To speed up compilation, the compute version specific to your GPU could be passed to cmake as, e.g., ``-DGPU_COMPUTE_VER=50``. A quick explanation and numbers for some architectures can be found `in this page <https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/>`_. 158 159.. note:: Enabling distributed GPU training 160 161 By default, distributed GPU training is disabled and only a single GPU will be used. To enable distributed GPU training, set the option ``USE_NCCL=ON``. Distributed GPU training depends on NCCL2, available at `this link <https://developer.nvidia.com/nccl>`_. Since NCCL2 is only available for Linux machines, **distributed GPU training is available only for Linux**. 162 163 .. code-block:: bash 164 165 mkdir build 166 cd build 167 cmake .. -DUSE_CUDA=ON -DUSE_NCCL=ON -DNCCL_ROOT=/path/to/nccl2 168 make -j4 169 170On Windows, run CMake as follows: 171 172.. code-block:: bash 173 174 mkdir build 175 cd build 176 cmake .. -G"Visual Studio 14 2015 Win64" -DUSE_CUDA=ON 177 178(Change the ``-G`` option appropriately if you have a different version of Visual Studio installed.) 179 180.. note:: Visual Studio 2017 Win64 Generator may not work 181 182 Choosing the Visual Studio 2017 generator may cause compilation failure. When it happens, specify the 2015 compiler by adding the ``-T`` option: 183 184 .. code-block:: bash 185 186 cmake .. -G"Visual Studio 15 2017 Win64" -T v140,cuda=8.0 -DUSE_CUDA=ON 187 188The above cmake configuration run will create an ``xgboost.sln`` solution file in the build directory. Build this solution in release mode as a x64 build, either from Visual studio or from command line: 189 190.. code-block:: bash 191 192 cmake --build . --target xgboost --config Release 193 194To speed up compilation, run multiple jobs in parallel by appending option ``-- /MP``. 195 196.. _build_python: 197 198*********************************** 199Building Python Package from Source 200*********************************** 201 202The Python package is located at ``python-package/``. 203 204Building Python Package with Default Toolchains 205=============================================== 206There are several ways to build and install the package from source: 207 2081. Use Python setuptools directly 209 210 The XGBoost Python package supports most of the setuptools commands, here is a list of tested commands: 211 212 .. code-block:: bash 213 214 python setup.py install # Install the XGBoost to your current Python environment. 215 python setup.py build # Build the Python package. 216 python setup.py build_ext # Build only the C++ core. 217 python setup.py sdist # Create a source distribution 218 python setup.py bdist # Create a binary distribution 219 python setup.py bdist_wheel # Create a binary distribution with wheel format 220 221 Running ``python setup.py install`` will compile XGBoost using default CMake flags. For 222 passing additional compilation options, append the flags to the command. For example, 223 to enable CUDA acceleration and NCCL (distributed GPU) support: 224 225 .. code-block:: bash 226 227 python setup.py install --use-cuda --use-nccl 228 229 Please refer to ``setup.py`` for a complete list of avaiable options. Some other 230 options used for development are only available for using CMake directly. See next 231 section on how to use CMake with setuptools manually. 232 233 You can install the created distribution packages using pip. For example, after running 234 ``sdist`` setuptools command, a tar ball similar to ``xgboost-1.0.0.tar.gz`` will be 235 created under the ``dist`` directory. Then you can install it by invoking the following 236 command under ``dist`` directory: 237 238 .. code-block:: bash 239 240 # under python-package directory 241 cd dist 242 pip install ./xgboost-1.0.0.tar.gz 243 244 245 For details about these commands, please refer to the official document of `setuptools 246 <https://setuptools.readthedocs.io/en/latest/>`_, or just Google "how to install Python 247 package from source". XGBoost Python package follows the general convention. 248 Setuptools is usually available with your Python distribution, if not you can install it 249 via system command. For example on Debian or Ubuntu: 250 251 .. code-block:: bash 252 253 sudo apt-get install python-setuptools 254 255 256 For cleaning up the directory after running above commands, ``python setup.py clean`` is 257 not sufficient. After copying out the build result, simply running ``git clean -xdf`` 258 under ``python-package`` is an efficient way to remove generated cache files. If you 259 find weird behaviors in Python build or running linter, it might be caused by those 260 cached files. 261 262 For using develop command (editable installation), see next section. 263 264 .. code-block:: 265 266 python setup.py develop # Create a editable installation. 267 pip install -e . # Same as above, but carried out by pip. 268 269 2702. Build C++ core with CMake first 271 272 This is mostly for C++ developers who don't want to go through the hooks in Python 273 setuptools. You can build C++ library directly using CMake as described in above 274 sections. After compilation, a shared object (or called dynamic linked library, jargon 275 depending on your platform) will appear in XGBoost's source tree under ``lib/`` 276 directory. On Linux distributions it's ``lib/libxgboost.so``. From there all Python 277 setuptools commands will reuse that shared object instead of compiling it again. This 278 is especially convenient if you are using the editable installation, where the installed 279 package is simply a link to the source tree. We can perform rapid testing during 280 development. Here is a simple bash script does that: 281 282 .. code-block:: bash 283 284 # Under xgboost source tree. 285 mkdir build 286 cd build 287 cmake .. 288 make -j$(nproc) 289 cd ../python-package 290 pip install -e . # or equivalently python setup.py develop 291 2923. Use ``libxgboost.so`` on system path. 293 294 This is for distributing xgboost in a language independent manner, where 295 ``libxgboost.so`` is separately packaged with Python package. Assuming `libxgboost.so` 296 is already presented in system library path, which can be queried via: 297 298 .. code-block:: python 299 300 import sys 301 import os 302 os.path.join(sys.prefix, 'lib') 303 304 Then one only needs to provide an user option when installing Python package to reuse the 305 shared object in system path: 306 307 .. code-block:: bash 308 309 cd xgboost/python-package 310 python setup.py install --use-system-libxgboost 311 312 313.. _python_mingw: 314 315Building Python Package for Windows with MinGW-w64 (Advanced) 316============================================================= 317 318Windows versions of Python are built with Microsoft Visual Studio. Usually Python binary modules are built with the same compiler the interpreter is built with. However, you may not be able to use Visual Studio, for following reasons: 319 3201. VS is proprietary and commercial software. Microsoft provides a freeware "Community" edition, but its licensing terms impose restrictions as to where and how it can be used. 3212. Visual Studio contains telemetry, as documented in `Microsoft Visual Studio Licensing Terms <https://visualstudio.microsoft.com/license-terms/mt736442/>`_. Running software with telemetry may be against the policy of your organization. 322 323So you may want to build XGBoost with GCC own your own risk. This presents some difficulties because MSVC uses Microsoft runtime and MinGW-w64 uses own runtime, and the runtimes have different incompatible memory allocators. But in fact this setup is usable if you know how to deal with it. Here is some experience. 324 3251. The Python interpreter will crash on exit if XGBoost was used. This is usually not a big issue. 3262. ``-O3`` is OK. 3273. ``-mtune=native`` is also OK. 3284. Don't use ``-march=native`` gcc flag. Using it causes the Python interpreter to crash if the DLL was actually used. 3295. You may need to provide the lib with the runtime libs. If ``mingw32/bin`` is not in ``PATH``, build a wheel (``python setup.py bdist_wheel``), open it with an archiver and put the needed dlls to the directory where ``xgboost.dll`` is situated. Then you can install the wheel with ``pip``. 330 331******************************* 332Building R Package From Source. 333******************************* 334 335By default, the package installed by running ``install.packages`` is built from source. 336Here we list some other options for installing development version. 337 338Installing the development version (Linux / Mac OSX) 339==================================================== 340 341Make sure you have installed git and a recent C++ compiler supporting C++11 (See above 342sections for requirements of building C++ core). 343 344Due to the use of git-submodules, ``devtools::install_github`` can no longer be used to install the latest version of R package. 345Thus, one has to run git to check out the code first: 346 347.. code-block:: bash 348 349 git clone --recursive https://github.com/dmlc/xgboost 350 cd xgboost 351 git submodule init 352 git submodule update 353 mkdir build 354 cd build 355 cmake .. -DR_LIB=ON 356 make -j$(nproc) 357 make install 358 359If all fails, try `Building the shared library`_ to see whether a problem is specific to R 360package or not. Notice that the R package is installed by CMake directly. 361 362Installing the development version with Visual Studio (Windows) 363=============================================================== 364 365On Windows, CMake with Visual C++ Build Tools (or Visual Studio) can be used to build the R package. 366 367While not required, this build can be faster if you install the R package ``processx`` with ``install.packages("processx")``. 368 369.. note:: Setting correct PATH environment variable on Windows 370 371 If you are using Windows, make sure to include the right directories in the PATH environment variable. 372 373 * If you are using R 4.x with RTools 4.0: 374 - ``C:\rtools40\usr\bin`` 375 - ``C:\rtools40\mingw64\bin`` 376 377 * If you are using R 3.x with RTools 3.x: 378 379 - ``C:\Rtools\bin`` 380 - ``C:\Rtools\mingw_64\bin`` 381 382Open the Command Prompt and navigate to the XGBoost directory, and then run the following commands. Make sure to specify the correct R version. 383 384.. code-block:: bash 385 386 cd C:\path\to\xgboost 387 mkdir build 388 cd build 389 cmake .. -G"Visual Studio 16 2019" -A x64 -DR_LIB=ON -DR_VERSION=4.0.0 390 cmake --build . --target install --config Release 391 392 393.. _r_gpu_support: 394 395Building R package with GPU support 396=================================== 397 398The procedure and requirements are similar as in :ref:`build_gpu_support`, so make sure to read it first. 399 400On Linux, starting from the XGBoost directory type: 401 402.. code-block:: bash 403 404 mkdir build 405 cd build 406 cmake .. -DUSE_CUDA=ON -DR_LIB=ON 407 make install -j$(nproc) 408 409When default target is used, an R package shared library would be built in the ``build`` area. 410The ``install`` target, in addition, assembles the package files with this shared library under ``build/R-package`` and runs ``R CMD INSTALL``. 411 412On Windows, CMake with Visual Studio has to be used to build an R package with GPU support. Rtools must also be installed. 413 414.. note:: Setting correct PATH environment variable on Windows 415 416 If you are using Windows, make sure to include the right directories in the PATH environment variable. 417 418 * If you are using R 4.x with RTools 4.0: 419 420 - ``C:\rtools40\usr\bin`` 421 - ``C:\rtools40\mingw64\bin`` 422 * If you are using R 3.x with RTools 3.x: 423 424 - ``C:\Rtools\bin`` 425 - ``C:\Rtools\mingw_64\bin`` 426 427Open the Command Prompt and navigate to the XGBoost directory, and then run the following commands. Make sure to specify the correct R version. 428 429.. code-block:: bash 430 431 cd C:\path\to\xgboost 432 mkdir build 433 cd build 434 cmake .. -G"Visual Studio 16 2019" -A x64 -DUSE_CUDA=ON -DR_LIB=ON -DR_VERSION=4.0.0 435 cmake --build . --target install --config Release 436 437If CMake can't find your R during the configuration step, you might provide the location of R to CMake like this: ``-DLIBR_HOME="C:\Program Files\R\R-4.0.0"``. 438 439If on Windows you get a "permission denied" error when trying to write to ...Program Files/R/... during the package installation, create a ``.Rprofile`` file in your personal home directory (if you don't already have one in there), and add a line to it which specifies the location of your R packages user library, like the following: 440 441.. code-block:: R 442 443 .libPaths( unique(c("C:/Users/USERNAME/Documents/R/win-library/3.4", .libPaths()))) 444 445You might find the exact location by running ``.libPaths()`` in R GUI or RStudio. 446 447 448********************* 449Building JVM Packages 450********************* 451 452Building XGBoost4J using Maven requires Maven 3 or newer, Java 7+ and CMake 3.13+ for compiling Java code as well as the Java Native Interface (JNI) bindings. 453 454Before you install XGBoost4J, you need to define environment variable ``JAVA_HOME`` as your JDK directory to ensure that your compiler can find ``jni.h`` correctly, since XGBoost4J relies on JNI to implement the interaction between the JVM and native libraries. 455 456After your ``JAVA_HOME`` is defined correctly, it is as simple as run ``mvn package`` under jvm-packages directory to install XGBoost4J. You can also skip the tests by running ``mvn -DskipTests=true package``, if you are sure about the correctness of your local setup. 457 458To publish the artifacts to your local maven repository, run 459 460.. code-block:: bash 461 462 mvn install 463 464Or, if you would like to skip tests, run 465 466.. code-block:: bash 467 468 mvn -DskipTests install 469 470This command will publish the xgboost binaries, the compiled java classes as well as the java sources to your local repository. Then you can use XGBoost4J in your Java projects by including the following dependency in ``pom.xml``: 471 472.. code-block:: xml 473 474 <dependency> 475 <groupId>ml.dmlc</groupId> 476 <artifactId>xgboost4j</artifactId> 477 <version>latest_source_version_num</version> 478 </dependency> 479 480For sbt, please add the repository and dependency in build.sbt as following: 481 482.. code-block:: scala 483 484 resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/repository" 485 486 "ml.dmlc" % "xgboost4j" % "latest_source_version_num" 487 488If you want to use XGBoost4J-Spark, replace ``xgboost4j`` with ``xgboost4j-spark``. 489 490.. note:: XGBoost4J-Spark requires Apache Spark 2.3+ 491 492 XGBoost4J-Spark now requires **Apache Spark 2.3+**. Latest versions of XGBoost4J-Spark uses facilities of `org.apache.spark.ml.param.shared` extensively to provide for a tight integration with Spark MLLIB framework, and these facilities are not fully available on earlier versions of Spark. 493 494 Also, make sure to install Spark directly from `Apache website <https://spark.apache.org/>`_. **Upstream XGBoost is not guaranteed to work with third-party distributions of Spark, such as Cloudera Spark.** Consult appropriate third parties to obtain their distribution of XGBoost. 495 496Enabling OpenMP for Mac OS 497========================== 498If you are on Mac OS and using a compiler that supports OpenMP, you need to go to the file ``xgboost/jvm-packages/create_jni.py`` and comment out the line 499 500.. code-block:: python 501 502 CONFIG["USE_OPENMP"] = "OFF" 503 504in order to get the benefit of multi-threading. 505 506Building with GPU support 507========================== 508If you want to build XGBoost4J that supports distributed GPU training, run 509 510.. code-block:: bash 511 512 mvn -Duse.cuda=ON install 513 514************************** 515Building the Documentation 516************************** 517XGBoost uses `Sphinx <https://www.sphinx-doc.org/en/stable/>`_ for documentation. To build it locally, you need a installed XGBoost with all its dependencies along with: 518 519* System dependencies 520 521 - git 522 - graphviz 523 524* Python dependencies 525 526 - sphinx 527 - breathe 528 - guzzle_sphinx_theme 529 - recommonmark 530 - mock 531 - sh 532 - graphviz 533 - matplotlib 534 535Under ``xgboost/doc`` directory, run ``make <format>`` with ``<format>`` replaced by the format you want. For a list of supported formats, run ``make help`` under the same directory. 536 537********* 538Makefiles 539********* 540 541It's only used for creating shorthands for running linters, performing packaging tasks 542etc. So the remaining makefiles are legacy. 543