Installation Guide

Here is the guide for the build of CLI version.

For the build of Python-package and R-package, please refer to Python-package and R-package folders respectively.

Windows

LightGBM can use Visual Studio, MSBuild with CMake or MinGW to build in Windows.

Visual Studio (or MSBuild)

With GUI

  1. Install Visual Studio (2015 or newer).

  2. Download zip archive and unzip it.

  3. Go to LightGBM-master/windows folder.

  4. 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

  1. Install Git for Windows, CMake (3.8 or higher) and MSBuild (MSBuild is not needed if Visual Studio (2015 or newer) is installed).

  2. Run the following commands:

    git clone --recursive https://github.com/Microsoft/LightGBM
    cd LightGBM
    mkdir build
    cd build
    cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..
    cmake --build . --target ALL_BUILD --config Release
    

The exe and dll files will be in LightGBM/Release folder.

MinGW64

  1. Install Git for Windows, CMake and MinGW-w64.

  2. Run the following commands:

    git clone --recursive https://github.com/Microsoft/LightGBM
    cd LightGBM
    mkdir build
    cd build
    cmake -G "MinGW Makefiles" ..
    mingw32-make.exe -j4
    

The exe and dll files will be in LightGBM/ folder.

Note: You may need to run the cmake -G "MinGW Makefiles" .. one more time if met sh.exe was found in your PATH error.

Also you may want to read gcc Tips.

Linux

LightGBM uses CMake to build. Run the following commands:

git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
mkdir build ; cd build
cmake ..
make -j4

Note: glibc >= 2.14 is required.

Also you may want to read gcc Tips.

macOS

LightGBM depends on OpenMP for compiling, which isn’t supported by Apple Clang.

Please install gcc/g++ by using the following commands:

brew install cmake
brew install gcc

Then install LightGBM:

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
mkdir build ; cd build
cmake ..
make -j4

Also you may want to read gcc Tips.

Docker

Refer to Docker folder.

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 parallel learning application with high performance communication, you can build the LightGBM with MPI support.

Windows

With GUI

  1. You need to install MS MPI first. Both msmpisdk.msi and MSMpiSetup.exe are needed.

  2. Install Visual Studio (2015 or newer).

  3. Download zip archive and unzip it.

  4. Go to LightGBM-master/windows folder.

  5. 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

  1. You need to install MS MPI first. Both msmpisdk.msi and MSMpiSetup.exe are needed.

  2. Install Git for Windows, CMake (3.8 or higher) and MSBuild (MSBuild is not needed if Visual Studio (2015 or newer) is installed).

  3. Run the following commands:

    git clone --recursive https://github.com/Microsoft/LightGBM
    cd LightGBM
    mkdir build
    cd build
    cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_MPI=ON ..
    cmake --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

You need to install Open MPI first.

Then run the following commands:

git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
mkdir build ; cd build
cmake -DUSE_MPI=ON ..
make -j4

Note: glibc >= 2.14 is required.

macOS

Install Open MPI first:

brew install open-mpi
brew install cmake

Then 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
mkdir build ; cd build
cmake -DUSE_MPI=ON ..
make -j4

Build GPU Version

Linux

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 cl-icd-libopencl1 and cl-icd-opencl-dev) can also be used.

  • libboost 1.56 or later (1.61 or later 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 3.2 or later.

To build LightGBM GPU version, run the following commands:

git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
mkdir build ; cd build
cmake -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 -DUSE_GPU=1 -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/ ..
make -j4

Windows

If you use MinGW, the build procedure are similar to the build in Linux. Refer to GPU Windows Compilation to get more details.

Following procedure is for the MSVC (Microsoft Visual C++) build.

  1. Install Git for Windows, CMake (3.8 or higher) and MSBuild (MSBuild is not needed if Visual Studio (2015 or newer) is installed).

  2. Install OpenCL for Windows. The installation depends on the brand (NVIDIA, AMD, Intel) of your GPU card.

    Further reading and correspondence table: GPU SDK Correspondence and Device Targeting Table.

  3. Install Boost Binary.

    Note: Match your Visual C++ version:

    Visual Studio 2015 -> msvc-14.0-64.exe,

    Visual Studio 2017 -> msvc-14.1-64.exe.

  4. Run the following commands:

    Set BOOST_ROOT=C:\local\boost_1_64_0\
    Set BOOST_LIBRARYDIR=C:\local\boost_1_64_0\lib64-msvc-14.0
    git clone --recursive https://github.com/Microsoft/LightGBM
    cd LightGBM
    mkdir build
    cd build
    cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_GPU=1 ..
    cmake --build . --target ALL_BUILD --config Release
    

    Note: C:\local\boost_1_64_0\ and C:\local\boost_1_64_0\lib64-msvc-14.0 are locations of your Boost binaries. You also can set them to the environment variable to avoid Set ... commands when build.

Docker

Refer to GPU Docker folder.

Build HDFS Version

Windows

Visual Studio (or MSBuild)

  1. Install Git for Windows, CMake (3.8 or higher) and MSBuild (MSBuild is not needed if Visual Studio (2015 or newer) is installed).

  2. Run the following commands:

    git clone --recursive https://github.com/Microsoft/LightGBM
    cd LightGBM
    mkdir build
    cd build
    cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_HDFS=ON ..
    cmake --build . --target ALL_BUILD --config Release
    

MinGW64

  1. Install Git for Windows, CMake and MinGW-w64.

  2. Run the following commands:

    git clone --recursive https://github.com/Microsoft/LightGBM
    cd LightGBM
    mkdir build
    cd build
    cmake -G "MinGW Makefiles" -DUSE_HDFS=ON ..
    mingw32-make.exe -j4
    

Linux

LightGBM uses CMake to build. Run the following commands:

git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
mkdir build ; cd build
cmake -DUSE_HDFS=ON ..
make -j4

macOS

LightGBM depends on OpenMP for compiling, which isn’t supported by Apple Clang.

Please install gcc/g++ by using the following commands:

brew install cmake
brew install gcc

Then install LightGBM:

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
mkdir build ; cd build
cmake -DUSE_HDFS=ON ..
make -j4

Build Java Wrapper

Linux

You need to install SWIG and Java first.

Then run the following commands:

git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
mkdir build ; cd build
cmake -DUSE_SWIG=ON ..
make -j4

This will generate a JAR file containing the LightGBM C API wrapped by SWIG.