Installation Guide
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: .
Windows
On Windows, LightGBM can be built using
Visual Studio;
CMake and VS Build Tools;
CMake and MinGW.
Visual Studio (or VS Build Tools)
With GUI
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.
From Command Line
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.
MinGW-w64
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).
Linux
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.
gcc
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
Clang
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
macOS
On macOS, LightGBM can be installed using
Homebrew;
MacPorts;
or can be built using
CMake and Apple Clang;
CMake and gcc.
Install Using Homebrew
brew install lightgbm
Refer to https://formulae.brew.sh/formula/lightgbm for more details.
Install Using MacPorts
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.
Build from GitHub
After compilation the executable and .dylib
files will be in LightGBM/
folder.
Apple Clang
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
gcc
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
Docker
Refer to Docker folder.
Build Threadless Version (not Recommended)
The default build version of LightGBM is based on OpenMP. You can build LightGBM without OpenMP support but it is strongly not recommended.
Windows
On Windows, a version of LightGBM without OpenMP support can be built using
Visual Studio;
CMake and VS Build Tools;
CMake and MinGW.
Visual Studio (or VS Build Tools)
With GUI
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.
From Command Line
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.
MinGW-w64
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.
Linux
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.
gcc
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
Clang
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
macOS
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.
Apple Clang
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
gcc
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
Build MPI Version
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.
Windows
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.
With GUI
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.
From Command Line
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.
Linux
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.
gcc
Clang
macOS
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.
Apple Clang
gcc
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
Build GPU Version
Windows
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.
Linux
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.
gcc
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
Clang
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
macOS
The GPU version is not supported on macOS.
Docker
Refer to GPU Docker folder.
Build CUDA Version
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.
Windows
The CUDA version is not supported on Windows.
Use the GPU version (device_type=gpu
) for GPU acceleration on Windows.
Linux
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.
gcc
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
Clang
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
macOS
The CUDA version is not supported on macOS.
Build Java Wrapper
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.
Windows
On Windows, a Java wrapper of LightGBM can be built using
Java, SWIG, CMake and VS Build Tools;
Java, SWIG, CMake and MinGW.
VS Build Tools
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
MinGW-w64
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).
Linux
On Linux, a Java wrapper of LightGBM can be built using
CMake, gcc, Java and SWIG;
CMake, Clang, Java and SWIG.
gcc
Clang
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
macOS
On macOS, a Java wrapper of LightGBM can be built using
CMake, Java, SWIG and Apple Clang;
CMake, Java, SWIG and gcc.
Apple Clang
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
gcc
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
Build Python-package
Refer to Python-package folder.
Build R-package
Refer to R-package folder.
Build C++ Unit Tests
Windows
On Windows, C++ unit tests of LightGBM can be built using
CMake and VS Build Tools;
CMake and MinGW.
VS Build Tools
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.
MinGW-w64
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.
Linux
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.
gcc
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
Clang
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
macOS
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.
Apple Clang
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
gcc
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