All instructions below are aimed at compiling the 64-bit version of LightGBM. It is worth compiling the 32-bit version only in very rare special cases involving environmental limitations. The 32-bit version is slow and untested, so use it at your own risk and don't forget to adjust some of the commands below when installing.
By default, instructions below will use VS Build Tools or make tool to compile the code.
It it possible to use Ninja tool instead of make on all platforms, but VS Build Tools cannot be replaced with Ninja.
You can add -G Ninja
to CMake flags to use Ninja.
By default, instructions below will produce a shared library file and an executable file with command-line interface.
You can add -DBUILD_CLI=OFF
to CMake flags to disable the executable compilation.
If you need to build a static library instead of a shared one, you can add -DBUILD_STATIC_LIB=ON
to CMake flags.
By default, instructions below will place header files into system-wide folder.
You can add -DINSTALL_HEADERS=OFF
to CMake flags to disable headers installation.
By default, on macOS, CMake is looking into Homebrew standard folders for finding dependencies (e.g. OpenMP).
You can add -DUSE_HOMEBREW_FALLBACK=OFF
to CMake flags to disable this behaviour.
Users who want to perform benchmarking can make LightGBM output time costs for different internal routines by adding -DUSE_TIMETAG=ON
to CMake flags.
It is possible to build LightGBM in debug mode.
In this mode all compiler optimizations are disabled and LightGBM performs more checks internally.
To enable debug mode you can add -DUSE_DEBUG=ON
to CMake flags or choose Debug_*
configuration (e.g. Debug_DLL
, Debug_mpi
) in Visual Studio depending on how you are building LightGBM.
In addition to the debug mode, LightGBM can be built with compiler sanitizers.
To enable them add -DUSE_SANITIZER=ON -DENABLED_SANITIZERS="address;leak;undefined"
to CMake flags.
These values refer to the following supported sanitizers:
address
- AddressSanitizer (ASan);leak
- LeakSanitizer (LSan);undefined
- UndefinedBehaviorSanitizer (UBSan);thread
- ThreadSanitizer (TSan).
Please note, that ThreadSanitizer cannot be used together with other sanitizers. For more info and additional sanitizers' parameters please refer to the following docs. It is very useful to build C++ unit tests with sanitizers.
You can download the artifacts of the latest successful build on master branch (nightly builds) here: .
Contents
On Windows, LightGBM can be built using
- Visual Studio;
- CMake and VS Build Tools;
- CMake and MinGW.
Install Visual Studio.
Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download
LightGBM-complete_source_code_zip.zip
, and unzip it.Go to
LightGBM-complete_source_code_zip/windows
folder.Open
LightGBM.sln
file with Visual Studio, chooseRelease
configuration if you need executable file orDLL
configuration if you need shared library and clickBuild
->Build Solution (Ctrl+Shift+B)
.If you have errors about Platform Toolset, go to
Project
->Properties
->Configuration Properties
->General
and select the toolset installed on your machine.
The .exe
file will be in LightGBM-complete_source_code_zip/windows/x64/Release
folder.
The .dll
file will be in LightGBM-complete_source_code_zip/windows/x64/DLL
folder.
Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio is already installed).
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -A x64 cmake --build build --target ALL_BUILD --config Release
The .exe
and .dll
files will be in LightGBM/Release
folder.
Install Git for Windows, CMake and MinGW-w64.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -G "MinGW Makefiles" cmake --build build -j4
The .exe
and .dll
files will be in LightGBM/
folder.
Note: You may need to run the cmake -B build -S . -G "MinGW Makefiles"
one more time or add -DCMAKE_SH=CMAKE_SH-NOTFOUND
to CMake flags if you encounter the sh.exe was found in your PATH
error.
It is recommended that you use Visual Studio since it has better multithreading efficiency in Windows for many-core systems (see Question 4 and Question 8).
On Linux, LightGBM can be built using
- CMake and gcc;
- CMake and Clang.
After compilation the executable and .so
files will be in LightGBM/
folder.
Install CMake and gcc.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . cmake --build build -j4
Install CMake, Clang and OpenMP.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . cmake --build build -j4
On macOS, LightGBM can be installed using
- Homebrew;
- MacPorts;
or can be built using
- CMake and Apple Clang;
- CMake and gcc.
brew install lightgbm
Refer to https://formulae.brew.sh/formula/lightgbm for more details.
sudo port install LightGBM
Refer to https://ports.macports.org/port/LightGBM for more details.
Note: Port for LightGBM is not maintained by LightGBM's maintainers.
After compilation the executable and .dylib
files will be in LightGBM/
folder.
Install CMake and OpenMP:
brew install cmake libomp
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . cmake --build build -j4
Install CMake and gcc:
brew install cmake gcc
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7 CC=gcc-7 # replace "7" with version of gcc installed on your machine cmake -B build -S . cmake --build build -j4
Refer to Docker folder.
The default build version of LightGBM is based on OpenMP. You can build LightGBM without OpenMP support but it is strongly not recommended.
On Windows, a version of LightGBM without OpenMP support can be built using
- Visual Studio;
- CMake and VS Build Tools;
- CMake and MinGW.
Install Visual Studio.
Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download
LightGBM-complete_source_code_zip.zip
, and unzip it.Go to
LightGBM-complete_source_code_zip/windows
folder.Open
LightGBM.sln
file with Visual Studio, chooseRelease
configuration if you need executable file orDLL
configuration if you need shared library.Go to
Project
->Properties
->Configuration Properties
->C/C++
->Language
and change theOpenMP Support
property toNo (/openmp-)
.Get back to the project's main screen and click
Build
->Build Solution (Ctrl+Shift+B)
.If you have errors about Platform Toolset, go to
Project
->Properties
->Configuration Properties
->General
and select the toolset installed on your machine.
The .exe
file will be in LightGBM-complete_source_code_zip/windows/x64/Release
folder.
The .dll
file will be in LightGBM-complete_source_code_zip/windows/x64/DLL
folder.
Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio is already installed).
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -A x64 -DUSE_OPENMP=OFF cmake --build build --target ALL_BUILD --config Release
The .exe
and .dll
files will be in LightGBM/Release
folder.
Install Git for Windows, CMake and MinGW-w64.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF cmake --build build -j4
The .exe
and .dll
files will be in LightGBM/
folder.
Note: You may need to run the cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF
one more time or add -DCMAKE_SH=CMAKE_SH-NOTFOUND
to CMake flags if you encounter the sh.exe was found in your PATH
error.
On Linux, a version of LightGBM without OpenMP support can be built using
- CMake and gcc;
- CMake and Clang.
After compilation the executable and .so
files will be in LightGBM/
folder.
Install CMake and gcc.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_OPENMP=OFF cmake --build build -j4
Install CMake and Clang.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . -DUSE_OPENMP=OFF cmake --build build -j4
On macOS, a version of LightGBM without OpenMP support can be built using
- CMake and Apple Clang;
- CMake and gcc.
After compilation the executable and .dylib
files will be in LightGBM/
folder.
Install CMake:
brew install cmake
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_OPENMP=OFF cmake --build build -j4
Install CMake and gcc:
brew install cmake gcc
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7 CC=gcc-7 # replace "7" with version of gcc installed on your machine cmake -B build -S . -DUSE_OPENMP=OFF cmake --build build -j4
The default build version of LightGBM is based on socket. LightGBM also supports MPI. MPI is a high performance communication approach with RDMA support.
If you need to run a distributed learning application with high performance communication, you can build the LightGBM with MPI support.
On Windows, an MPI version of LightGBM can be built using
- MS MPI and Visual Studio;
- MS MPI, CMake and VS Build Tools.
Note: Building MPI version by MinGW is not supported due to the miss of MPI library in it.
You need to install MS MPI first. Both
msmpisdk.msi
andmsmpisetup.exe
are needed.Install Visual Studio.
Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download
LightGBM-complete_source_code_zip.zip
, and unzip it.Go to
LightGBM-complete_source_code_zip/windows
folder.Open
LightGBM.sln
file with Visual Studio, chooseRelease_mpi
configuration and clickBuild
->Build Solution (Ctrl+Shift+B)
.If you have errors about Platform Toolset, go to
Project
->Properties
->Configuration Properties
->General
and select the toolset installed on your machine.
The .exe
file will be in LightGBM-complete_source_code_zip/windows/x64/Release_mpi
folder.
You need to install MS MPI first. Both
msmpisdk.msi
andmsmpisetup.exe
are needed.Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio is already installed).
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -A x64 -DUSE_MPI=ON cmake --build build --target ALL_BUILD --config Release
The .exe
and .dll
files will be in LightGBM/Release
folder.
On Linux, an MPI version of LightGBM can be built using
- CMake, gcc and Open MPI;
- CMake, Clang and Open MPI.
After compilation the executable and .so
files will be in LightGBM/
folder.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_MPI=ON cmake --build build -j4
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . -DUSE_MPI=ON cmake --build build -j4
On macOS, an MPI version of LightGBM can be built using
- CMake, Open MPI and Apple Clang;
- CMake, Open MPI and gcc.
After compilation the executable and .dylib
files will be in LightGBM/
folder.
Install CMake, OpenMP and Open MPI:
brew install cmake libomp open-mpi
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_MPI=ON cmake --build build -j4
Install CMake, Open MPI and gcc:
brew install cmake open-mpi gcc
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7 CC=gcc-7 # replace "7" with version of gcc installed on your machine cmake -B build -S . -DUSE_MPI=ON cmake --build build -j4
On Windows, a GPU version of LightGBM (device_type=gpu
) can be built using
- OpenCL, Boost, CMake and VS Build Tools;
- OpenCL, Boost, CMake and MinGW.
If you use MinGW, the build procedure is similar to the build on Linux.
Following procedure is for the MSVC (Microsoft Visual C++) build.
Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio is installed).
Install OpenCL for Windows. The installation depends on the brand (NVIDIA, AMD, Intel) of your GPU card.
- For running on Intel, get Intel SDK for OpenCL.
- For running on AMD, get AMD APP SDK.
- For running on NVIDIA, get CUDA Toolkit.
Further reading and correspondence table: GPU SDK Correspondence and Device Targeting Table.
Install Boost Binaries.
Note: Match your Visual C++ version:
Visual Studio 2015 ->
msvc-14.0-64.exe
,Visual Studio 2017 ->
msvc-14.1-64.exe
,Visual Studio 2019 ->
msvc-14.2-64.exe
,Visual Studio 2022 ->
msvc-14.3-64.exe
.Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -A x64 -DUSE_GPU=ON -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0 # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following: # cmake -B build -S . -A x64 -DUSE_GPU=ON -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0 -DOpenCL_LIBRARY="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.0/lib/x64/OpenCL.lib" -DOpenCL_INCLUDE_DIR="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.0/include" cmake --build build --target ALL_BUILD --config Release
Note:
C:/local/boost_1_63_0
andC:/local/boost_1_63_0/lib64-msvc-14.0
are locations of your Boost binaries (assuming you've downloaded 1.63.0 version for Visual Studio 2015).
The .exe
and .dll
files will be in LightGBM/Release
folder.
On Linux, a GPU version of LightGBM (device_type=gpu
) can be built using
- CMake, OpenCL, Boost and gcc;
- CMake, OpenCL, Boost and Clang.
OpenCL headers and libraries are usually provided by GPU manufacture.
The generic OpenCL ICD packages (for example, Debian packages ocl-icd-libopencl1
, ocl-icd-opencl-dev
, pocl-opencl-icd
) can also be used.
Required Boost libraries (Boost.Align, Boost.System, Boost.Filesystem, Boost.Chrono) should be provided by the following Debian packages: libboost-dev
, libboost-system-dev
, libboost-filesystem-dev
, libboost-chrono-dev
.
After compilation the executable and .so
files will be in LightGBM/
folder.
Install CMake, gcc, OpenCL and Boost.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_GPU=ON # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following: # cmake -B build -S . -DUSE_GPU=ON -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/ cmake --build build -j4
Install CMake, Clang, OpenMP, OpenCL and Boost.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . -DUSE_GPU=ON # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following: # cmake -B build -S . -DUSE_GPU=ON -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/ cmake --build build -j4
The GPU version is not supported on macOS.
Refer to GPU Docker folder.
The original GPU version of LightGBM (device_type=gpu
) is based on OpenCL.
The CUDA-based version (device_type=cuda
) is a separate implementation.
Use this version in Linux environments with an NVIDIA GPU with compute capability 6.0 or higher.
The CUDA version is not supported on Windows.
Use the GPU version (device_type=gpu
) for GPU acceleration on Windows.
On Linux, a CUDA version of LightGBM can be built using
- CMake, gcc and CUDA;
- CMake, Clang and CUDA.
Please refer to this detailed guide for CUDA libraries installation.
After compilation the executable and .so
files will be in LightGBM/
folder.
Install CMake, gcc and CUDA.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_CUDA=ON cmake --build build -j4
Install CMake, Clang, OpenMP and CUDA.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . -DUSE_CUDA=ON cmake --build build -j4
The CUDA version is not supported on macOS.
Using the following instructions you can generate a JAR file containing the LightGBM C API wrapped by SWIG.
After compilation the .jar
file will be in LightGBM/build
folder.
On Windows, a Java wrapper of LightGBM can be built using
- Java, SWIG, CMake and VS Build Tools;
- Java, SWIG, CMake and MinGW.
Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio is already installed).
Install SWIG and Java (also make sure that
JAVA_HOME
environment variable is set properly).Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -A x64 -DUSE_SWIG=ON cmake --build build --target ALL_BUILD --config Release
Install Git for Windows, CMake and MinGW-w64.
Install SWIG and Java (also make sure that
JAVA_HOME
environment variable is set properly).Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON cmake --build build -j4
Note: You may need to run the cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON
one more time or add -DCMAKE_SH=CMAKE_SH-NOTFOUND
to CMake flags if you encounter the sh.exe was found in your PATH
error.
It is recommended to use VS Build Tools (Visual Studio) since it has better multithreading efficiency in Windows for many-core systems (see Question 4 and Question 8).
On Linux, a Java wrapper of LightGBM can be built using
- CMake, gcc, Java and SWIG;
- CMake, Clang, Java and SWIG.
Install CMake, gcc, SWIG and Java (also make sure that
JAVA_HOME
environment variable is set properly).Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_SWIG=ON cmake --build build -j4
Install CMake, Clang, OpenMP, SWIG and Java (also make sure that
JAVA_HOME
environment variable is set properly).Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . -DUSE_SWIG=ON cmake --build build -j4
On macOS, a Java wrapper of LightGBM can be built using
- CMake, Java, SWIG and Apple Clang;
- CMake, Java, SWIG and gcc.
Install CMake, Java (also make sure that
JAVA_HOME
environment variable is set properly), SWIG and OpenMP:brew install cmake openjdk swig libomp export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DUSE_SWIG=ON cmake --build build -j4
Install CMake, Java (also make sure that
JAVA_HOME
environment variable is set properly), SWIG and gcc:brew install cmake openjdk swig gcc export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7 CC=gcc-7 # replace "7" with version of gcc installed on your machine cmake -B build -S . -DUSE_SWIG=ON cmake --build build -j4
Refer to Python-package folder.
Refer to R-package folder.
On Windows, C++ unit tests of LightGBM can be built using
- CMake and VS Build Tools;
- CMake and MinGW.
Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio is already installed).
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -A x64 -DBUILD_CPP_TEST=ON cmake --build build --target testlightgbm --config Debug
The .exe
file will be in LightGBM/Debug
folder.
Install Git for Windows, CMake and MinGW-w64.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -G "MinGW Makefiles" -DBUILD_CPP_TEST=ON cmake --build build --target testlightgbm -j4
The .exe
file will be in LightGBM/
folder.
Note: You may need to run the cmake -B build -S . -G "MinGW Makefiles" -DBUILD_CPP_TEST=ON
one more time or add -DCMAKE_SH=CMAKE_SH-NOTFOUND
to CMake flags if you encounter the sh.exe was found in your PATH
error.
On Linux, a C++ unit tests of LightGBM can be built using
- CMake and gcc;
- CMake and Clang.
After compilation the executable file will be in LightGBM/
folder.
Install CMake and gcc.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DBUILD_CPP_TEST=ON cmake --build build --target testlightgbm -j4
Install CMake, Clang and OpenMP.
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine cmake -B build -S . -DBUILD_CPP_TEST=ON cmake --build build --target testlightgbm -j4
On macOS, a C++ unit tests of LightGBM can be built using
- CMake and Apple Clang;
- CMake and gcc.
After compilation the executable file will be in LightGBM/
folder.
Install CMake and OpenMP:
brew install cmake libomp
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM cmake -B build -S . -DBUILD_CPP_TEST=ON cmake --build build --target testlightgbm -j4
Install CMake and gcc:
brew install cmake gcc
Run the following commands:
git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7 CC=gcc-7 # replace "7" with version of gcc installed on your machine cmake -B build -S . -DBUILD_CPP_TEST=ON cmake --build build --target testlightgbm -j4