This page gives instructions on how to build and install XGBoost from the source code on various systems. If the instructions do not work for you, please feel free to ask questions at the user forum.
Note
Pre-built binary is available: now with GPU support
Consider installing XGBoost from a pre-built binary, to avoid the trouble of building XGBoost from the source. Checkout Installation Guide.
Contents
To obtain the development repository of XGBoost, one needs to use git.
Note
Use of Git submodules
XGBoost uses Git submodules to manage dependencies. So when you clone the repo, remember to specify --recursive option:
git clone --recursive https://github.com/dmlc/xgboost
For windows users who use github tools, you can open the git shell and type the following command:
git submodule init
git submodule update
The Python package is located at python-package/.
There are several ways to build and install the package from source:
Use Python setuptools directly
The XGBoost Python package supports most of the setuptools commands, here is a list of tested commands:
python setup.py install # Install the XGBoost to your current Python environment. python setup.py build # Build the Python package. python setup.py build_ext # Build only the C++ core. python setup.py sdist # Create a source distribution python setup.py bdist # Create a binary distribution python setup.py bdist_wheel # Create a binary distribution with wheel formatRunning
python setup.py installwill compile XGBoost using default CMake flags. For passing additional compilation options, append the flags to the command. For example, to enable CUDA acceleration and NCCL (distributed GPU) support:python setup.py install --use-cuda --use-ncclPlease refer to
setup.pyfor a complete list of avaiable options. Some other options used for development are only available for using CMake directly. See next section on how to use CMake with setuptools manually.You can install the created distribution packages using pip. For example, after running
sdistsetuptools command, a tar ball similar toxgboost-1.0.0.tar.gzwill be created under thedistdirectory. Then you can install it by invoking the following command underdistdirectory:# under python-package directory cd dist pip install ./xgboost-1.0.0.tar.gzFor details about these commands, please refer to the official document of setuptools, or just Google “how to install Python package from source”. XGBoost Python package follows the general convention. Setuptools is usually available with your Python distribution, if not you can install it via system command. For example on Debian or Ubuntu:
sudo apt-get install python-setuptoolsFor cleaning up the directory after running above commands,
python setup.py cleanis not sufficient. After copying out the build result, simply runninggit clean -xdfunderpython-packageis an efficient way to remove generated cache files. If you find weird behaviors in Python build or running linter, it might be caused by those cached files.For using develop command (editable installation), see next section.
python setup.py develop # Create a editable installation. pip install -e . # Same as above, but carried out by pip.
Build C++ core with CMake first
This is mostly for C++ developers who don’t want to go through the hooks in Python setuptools. You can build C++ library directly using CMake as described in above sections. After compilation, a shared object (or called dynamic linked library, jargon depending on your platform) will appear in XGBoost’s source tree under
lib/directory. On Linux distributions it’slib/libxgboost.so. From there all Python setuptools commands will reuse that shared object instead of compiling it again. This is especially convenient if you are using the editable installation, where the installed package is simply a link to the source tree. We can perform rapid testing during development. Here is a simple bash script does that:# Under xgboost source tree. mkdir build cd build cmake .. make -j$(nproc) cd ../python-package pip install -e . # or equivalently python setup.py develop
Use libxgboost.so on system path.
This is for distributing xgboost in a language independent manner, where
libxgboost.sois separately packaged with Python package. Assuming libxgboost.so is already presented in system library path, which can be queried via:import sys import os os.path.join(sys.prefix, 'lib')Then one only needs to provide an user option when installing Python package to reuse the shared object in system path:
cd xgboost/python-package python setup.py install --use-system-libxgboost
Windows 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:
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.
Visual Studio contains telemetry, as documented in Microsoft Visual Studio Licensing Terms. Running software with telemetry may be against the policy of your organization.
So 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.
The Python interpreter will crash on exit if XGBoost was used. This is usually not a big issue.
-O3 is OK.
-mtune=native is also OK.
Don’t use -march=native gcc flag. Using it causes the Python interpreter to crash if the DLL was actually used.
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.
By default, the package installed by running install.packages is built from source.
Here we list some other options for installing development version.
Make sure you have installed git and a recent C++ compiler supporting C++11 (See above sections for requirements of building C++ core).
Due to the use of git-submodules, devtools::install_github can no longer be used to install the latest version of R package.
Thus, one has to run git to check out the code first:
git clone --recursive https://github.com/dmlc/xgboost
cd xgboost
git submodule init
git submodule update
mkdir build
cd build
cmake .. -DR_LIB=ON
make -j$(nproc)
make install
If all fails, try Building the shared library to see whether a problem is specific to R package or not. Notice that the R package is installed by CMake directly.
On Windows, CMake with Visual C++ Build Tools (or Visual Studio) can be used to build the R package.
While not required, this build can be faster if you install the R package processx with install.packages("processx").
Note
Setting correct PATH environment variable on Windows
If you are using Windows, make sure to include the right directories in the PATH environment variable.
If you are using R 4.x with RTools 4.0:
- C:\rtools40\usr\bin
- C:\rtools40\mingw64\bin
If you are using R 3.x with RTools 3.x:
C:\Rtools\bin
C:\Rtools\mingw_64\bin
Open the Command Prompt and navigate to the XGBoost directory, and then run the following commands. Make sure to specify the correct R version.
cd C:\path\to\xgboost
mkdir build
cd build
cmake .. -G"Visual Studio 16 2019" -A x64 -DR_LIB=ON -DR_VERSION=4.0.0
cmake --build . --target install --config Release
The procedure and requirements are similar as in Building with GPU support, so make sure to read it first.
On Linux, starting from the XGBoost directory type:
mkdir build
cd build
cmake .. -DUSE_CUDA=ON -DR_LIB=ON
make install -j$(nproc)
When default target is used, an R package shared library would be built in the build area.
The install target, in addition, assembles the package files with this shared library under build/R-package and runs R CMD INSTALL.
On Windows, CMake with Visual Studio has to be used to build an R package with GPU support. Rtools must also be installed.
Note
Setting correct PATH environment variable on Windows
If you are using Windows, make sure to include the right directories in the PATH environment variable.
If you are using R 4.x with RTools 4.0:
C:\rtools40\usr\bin
C:\rtools40\mingw64\bin
If you are using R 3.x with RTools 3.x:
C:\Rtools\bin
C:\Rtools\mingw_64\bin
Open the Command Prompt and navigate to the XGBoost directory, and then run the following commands. Make sure to specify the correct R version.
cd C:\path\to\xgboost
mkdir build
cd build
cmake .. -G"Visual Studio 16 2019" -A x64 -DUSE_CUDA=ON -DR_LIB=ON -DR_VERSION=4.0.0
cmake --build . --target install --config Release
If 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".
If 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:
.libPaths( unique(c("C:/Users/USERNAME/Documents/R/win-library/3.4", .libPaths())))
You might find the exact location by running .libPaths() in R GUI or RStudio.
Building 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.
Before 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.
After 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.
To publish the artifacts to your local maven repository, run
mvn install
Or, if you would like to skip tests, run
mvn -DskipTests install
This 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:
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j</artifactId>
<version>latest_source_version_num</version>
</dependency>
For sbt, please add the repository and dependency in build.sbt as following:
resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/repository"
"ml.dmlc" % "xgboost4j" % "latest_source_version_num"
If you want to use XGBoost4J-Spark, replace xgboost4j with xgboost4j-spark.
Note
XGBoost4J-Spark requires Apache Spark 2.3+
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.
Also, make sure to install Spark directly from Apache website. 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.
If 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
CONFIG["USE_OPENMP"] = "OFF"
in order to get the benefit of multi-threading.
If you want to build XGBoost4J that supports distributed GPU training, run
mvn -Duse.cuda=ON install
XGBoost uses Sphinx for documentation. To build it locally, you need a installed XGBoost with all its dependencies along with:
System dependencies
git
graphviz
Python dependencies
sphinx
breathe
guzzle_sphinx_theme
recommonmark
mock
sh
graphviz
matplotlib
Under 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.
It’s only used for creating shorthands for running linters, performing packaging tasks etc. So the remaining makefiles are legacy.