Installation Guide

This is a guide for building the LightGBM Command Line Interface (CLI). If you want to build the Python-package or R-package please refer to Python-package and R-package folders respectively.

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.

If you need to build a static library instead of a shared one, you can add -DBUILD_STATIC_LIB=ON to CMake flags.

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 also 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 (2015 or newer).
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-master/windows folder.
Open LightGBM.sln file with Visual Studio, choose Release configuration 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-master/windows/x64/Release folder.

From Command Line

Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio (2015 or newer) 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 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 or Clang.

Install CMake.

Run the following commands:

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S .
cmake --build build -j4

Note: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

Using `Ninja`

On Linux, LightGBM can also be built with Ninja instead of make.

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -G 'Ninja'
cmake --build build -j2

macOS

On macOS LightGBM can be installed using Homebrew, or can be built using CMake and Apple Clang or gcc.

Apple Clang

Only Apple Clang version 8.1 or higher is supported.

Install Using `Homebrew`

brew install lightgbm

Build from GitHub

Install CMake :
```
brew install cmake
```
Install OpenMP:
```
brew install 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 :
```
brew install cmake
```
Install gcc:
```
brew install 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 (2015 or newer).
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-master/windows folder.
Open LightGBM.sln file with Visual Studio.
Go to PROJECT -> Properties -> Configuration Properties -> C/C++ -> Language and change the OpenMP Support property to No (/openmp-).
Get back to the project’s main screen, then choose Release configuration 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-master/windows/x64/Release folder.

From Command Line

Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio (2015 or newer) 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 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 or Clang.

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

macOS

On macOS a version of LightGBM without OpenMP support can be built using CMake and Apple Clang or gcc.

Apple Clang

Only Apple Clang version 8.1 or higher is supported.

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 :
```
brew install cmake
```
Install gcc:
```
brew install 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.

With GUI

You need to install MS MPI first. Both msmpisdk.msi and msmpisetup.exe are needed.
Install Visual Studio (2015 or newer).
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-master/windows folder.
Open LightGBM.sln file with Visual Studio, choose Release_mpi configuration 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-master/windows/x64/Release_mpi folder.

From Command Line

You need to install MS MPI first. Both msmpisdk.msi and msmpisetup.exe are needed.
Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio (2015 or newer) 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.

Note: Building MPI version by MinGW is not supported due to the miss of MPI library in it.

Linux

On Linux an MPI version of LightGBM can be built using Open MPI, CMake and gcc or Clang.

Install Open MPI.
Install CMake.

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

Note: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

macOS

On macOS an MPI version of LightGBM can be built using Open MPI, CMake and Apple Clang or gcc.

Apple Clang

Only Apple Clang version 8.1 or higher is supported.

Install CMake :
```
brew install cmake
```
Install OpenMP:
```
brew install libomp
```
Install Open MPI:
```
brew install 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

gcc

Install CMake :
```
brew install cmake
```
Install gcc:
```
brew install gcc
```
Install Open MPI:
```
brew install open-mpi
```

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

Linux

On Linux a GPU version of LightGBM (device_type=gpu) can be built using OpenCL, Boost, CMake and gcc or Clang.

The following dependencies should be installed before compilation:

OpenCL 1.2 headers and libraries, which is usually provided by GPU manufacture.

The generic OpenCL ICD packages (for example, Debian package ocl-icd-libopencl1 and ocl-icd-opencl-dev) can also be used.
libboost 1.56 or later (1.61 or later is recommended).

We use Boost.Compute as the interface to GPU, which is part of the Boost library since version 1.61. However, since we include the source code of Boost.Compute as a submodule, we only require the host has Boost 1.56 or later installed. We also use Boost.Align for memory allocation. Boost.Compute requires Boost.System and Boost.Filesystem to store offline kernel cache.

The following Debian packages should provide necessary Boost libraries: libboost-dev, libboost-system-dev, libboost-filesystem-dev.
CMake

To build LightGBM GPU version, run the following commands:

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_GPU=1
# 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=1 -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/
cmake --build build

Note: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

Windows

On Windows a GPU version of LightGBM (device_type=gpu) can be built using OpenCL, Boost, CMake and VS Build Tools or 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 (2015 or newer) 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=1 -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=1 -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 and C:/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).

Docker

Refer to GPU Docker folder.

Build CUDA Version

The original GPU build of LightGBM (device_type=gpu) is based on OpenCL.

The CUDA-based build (device_type=cuda) is a separate implementation. Use this version in Linux environments with an NVIDIA GPU with compute capability 6.0 or higher.

Linux

On Linux a CUDA version of LightGBM can be built using CUDA, CMake and gcc or Clang.

The following dependencies should be installed before compilation:

CUDA 11.0 or later libraries. Please refer to this detailed guide. Pay great attention to the minimum required versions of host compilers listed in the table from that guide and use only recommended versions of compilers.
CMake

To build LightGBM CUDA version, run the following commands:

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_CUDA=1
cmake --build build -j4

Note: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

macOS

The CUDA version is not supported on macOS.

Windows

The CUDA version is not supported on Windows. Use the GPU version (device_type=gpu) for GPU acceleration on Windows.

Build Java Wrapper

Using the following instructions you can generate a JAR file containing the LightGBM C API wrapped by SWIG.

Windows

On Windows a Java wrapper of LightGBM can be built using Java, SWIG, CMake and VS Build Tools or MinGW.

VS Build Tools

Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio (2015 or newer) is already installed).
Install SWIG and Java (also make sure that JAVA_HOME 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

The .jar file will be in LightGBM/build folder and the .dll files will be in LightGBM/Release folder.

MinGW-w64

Install Git for Windows, CMake and MinGW-w64.
Install SWIG and Java (also make sure that JAVA_HOME 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

The .jar file will be in LightGBM/build folder and the .dll files will be in LightGBM/ folder.

Note: You may need to run the cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON one more time 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 Java, SWIG, CMake and gcc or Clang.

Install CMake, SWIG and Java (also make sure that JAVA_HOME 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

Note: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

macOS

On macOS a Java wrapper of LightGBM can be built using Java, SWIG, CMake and Apple Clang or gcc.

First, install SWIG and Java (also make sure that JAVA_HOME is set properly). Then, either follow the Apple Clang or gcc installation instructions below.

Apple Clang

Only Apple Clang version 8.1 or higher is supported.

Install CMake :
```
brew install cmake
```
Install OpenMP:
```
brew install libomp
```

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 :
```
brew install cmake
```
Install gcc:
```
brew install 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_SWIG=ON
cmake --build build -j4

Build C++ Unit Tests

Windows

On Windows, C++ unit tests of LightGBM can be built using CMake and VS Build Tools.

Install Git for Windows, CMake and VS Build Tools (VS Build Tools is not needed if Visual Studio (2015 or newer) 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 -DUSE_OPENMP=OFF
cmake --build build --target testlightgbm --config Debug

The .exe file will be in LightGBM/Debug folder.

Linux

On Linux a C++ unit tests of LightGBM can be built using CMake and gcc or Clang.

Install CMake.

Run the following commands:

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
cmake --build build --target testlightgbm -j4

macOS

On macOS a C++ unit tests of LightGBM can be built using CMake and Apple Clang or gcc.

Apple Clang

Only Apple Clang version 8.1 or higher is supported.

Install CMake :
```
brew install cmake
```

Run the following commands:

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
cmake --build build --target testlightgbm -j4

gcc

Install CMake :
```
brew install cmake
```
Install gcc:
```
brew install 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 -DUSE_OPENMP=OFF
cmake --build build --target testlightgbm -j4

Installation Guide

Windows

Visual Studio (or VS Build Tools)

With GUI

From Command Line

MinGW-w64

Linux

Using Ninja

macOS

Apple Clang

Install Using Homebrew

Build from GitHub

gcc

Docker

Build Threadless Version (not Recommended)

Windows

Visual Studio (or VS Build Tools)

With GUI

From Command Line

MinGW-w64

Linux

macOS

Apple Clang

gcc

Build MPI Version

Windows

With GUI

From Command Line

Linux

macOS

Apple Clang

gcc

Build GPU Version

Linux

Windows

Docker

Build CUDA Version

Linux

macOS

Windows

Build Java Wrapper

Windows

VS Build Tools

MinGW-w64

Linux

macOS

Apple Clang

gcc

Build C++ Unit Tests

Windows

Linux

macOS

Apple Clang

gcc

Using `Ninja`

Install Using `Homebrew`