以下所有说明都旨在编译 LightGBM 的 64 位版本。仅在极少数涉及环境限制的特殊情况下才值得编译 32 位版本。32 位版本速度较慢且未经测试,因此请自行承担风险使用,并且在安装时不要忘记调整下面的一些命令。

默认情况下,以下说明将使用 VS Build Toolsmake 工具来编译代码。可以在所有平台上使用 Ninja 工具代替 make,但 VS Build Tools 无法被 Ninja 替代。您可以将 -G Ninja 添加到 CMake 标志中使用 Ninja。

默认情况下,以下说明将生成一个共享库文件和一个带命令行接口的可执行文件。您可以将 -DBUILD_CLI=OFF 添加到 CMake 标志以禁用可执行文件编译。

如果您需要构建静态库而不是共享库,您可以将 -DBUILD_STATIC_LIB=ON 添加到 CMake 标志。

默认情况下,以下说明会将头文件放置到系统范围的文件夹中。您可以将 -DINSTALL_HEADERS=OFF 添加到 CMake 标志以禁用头文件安装。

默认情况下,在 macOS 上,CMake 会在 Homebrew 标准文件夹中查找依赖项(例如 OpenMP)。您可以将 -DUSE_HOMEBREW_FALLBACK=OFF 添加到 CMake 标志以禁用此行为。

想要执行基准测试的用户可以通过将 -DUSE_TIMETAG=ON 添加到 CMake 标志,让 LightGBM 输出不同内部例程的时间成本。

可以在调试模式下构建 LightGBM。在此模式下,所有编译器优化都会被禁用,并且 LightGBM 会在内部执行更多检查。要启用调试模式,您可以将 -DUSE_DEBUG=ON 添加到 CMake 标志,或者根据您构建 LightGBM 的方式,在 Visual Studio 中选择 Debug_* 配置(例如 Debug_DLLDebug_mpi)。

除了调试模式,还可以使用编译器 sanitizer 构建 LightGBM。要启用它们,请将 -DUSE_SANITIZER=ON -DENABLED_SANITIZERS="address;leak;undefined" 添加到 CMake 标志。

这些值指的是以下支持的 sanitizer

  • address - AddressSanitizer (ASan);

  • leak - LeakSanitizer (LSan);

  • undefined - UndefinedBehaviorSanitizer (UBSan);

  • thread - ThreadSanitizer (TSan)。

请注意,ThreadSanitizer 不能与其他 sanitizer 一起使用。有关更多信息和其他 sanitizer 参数,请参考以下文档。使用 sanitizer 构建C++ 单元测试非常有用。

您可以在此处下载 master 分支上最新成功构建(夜间构建)的 artifact:下载 artifacts

Windows

在 Windows 上,可以使用以下方式构建 LightGBM

  • Visual Studio;

  • CMakeVS Build Tools

  • CMakeMinGW

Visual Studio(或 VS Build Tools)

使用 GUI

  1. 安装 Visual Studio

  2. 导航到 https://github.com/microsoft/LightGBM/releases 的某个发布版本,下载 LightGBM-complete_source_code_zip.zip,然后解压。

  3. 前往 LightGBM-complete_source_code_zip/windows 文件夹。

  4. 使用 Visual Studio 打开 LightGBM.sln 文件,如果需要可执行文件,选择 Release 配置;如果需要共享库,选择 DLL 配置;然后点击 Build -> Build Solution (Ctrl+Shift+B)

    如果出现关于 Platform Toolset 的错误,请前往 Project -> Properties -> Configuration Properties -> General 并选择机器上已安装的工具集。

.exe 文件将在 LightGBM-complete_source_code_zip/windows/x64/Release 文件夹中。.dll 文件将在 LightGBM-complete_source_code_zip/windows/x64/DLL 文件夹中。

通过命令行

  1. 安装 Git for WindowsCMakeVS Build Tools(如果已安装 Visual Studio,则不需要 VS Build Tools)。

  2. 运行以下命令

    git clone --recursive https://github.com/microsoft/LightGBM
    cd LightGBM
    cmake -B build -S . -A x64
    cmake --build build --target ALL_BUILD --config Release
    

.exe.dll 文件将在 LightGBM/Release 文件夹中。

MinGW-w64

  1. 安装 Git for WindowsCMakeMinGW-w64

  2. 运行以下命令

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

.exe.dll 文件将在 LightGBM/ 文件夹中。

注意:如果遇到 sh.exe was found in your PATH 错误,您可能需要再次运行 cmake -B build -S . -G "MinGW Makefiles" 或将 -DCMAKE_SH=CMAKE_SH-NOTFOUND 添加到 CMake 标志。

建议使用 Visual Studio,因为它在 Windows 多核系统上具有更好的多线程效率(请参阅问题 4问题 8)。

Linux

在 Linux 上,可以使用以下方式构建 LightGBM

  • CMakegcc

  • CMakeClang

编译后,可执行文件和 .so 文件将在 LightGBM/ 文件夹中。

gcc

  1. 安装 CMakegcc

  2. 运行以下命令

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

Clang

  1. 安装 CMakeClangOpenMP

  2. 运行以下命令

    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

在 macOS 上,可以使用以下方式安装 LightGBM

  • Homebrew;

  • MacPorts;

或使用以下方式构建

  • CMakeApple Clang

  • CMakegcc

使用 Homebrew 安装

brew install lightgbm

请参考 https://formulae.brew.sh/formula/lightgbm 获取更多详细信息。

使用 MacPorts 安装

sudo port install LightGBM

请参考 https://ports.macports.org/port/LightGBM 获取更多详细信息。

注意:LightGBM 的 Port 不由 LightGBM 的维护者维护。

从 GitHub 构建

编译后,可执行文件和 .dylib 文件将在 LightGBM/ 文件夹中。

Apple Clang

  1. 安装 CMakeOpenMP

    brew install cmake libomp
    
  2. 运行以下命令

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

gcc

  1. 安装 CMakegcc

    brew install cmake gcc
    
  2. 运行以下命令

    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

请参考 Docker 文件夹

构建 MPI 版本

LightGBM 的默认构建版本基于 socket。LightGBM 也支持 MPI。MPI 是一种支持 RDMA 的高性能通信方法。

如果您需要运行具有高性能通信的分布式学习应用程序,您可以构建支持 MPI 的 LightGBM。

Windows

在 Windows 上,可以使用以下方式构建 LightGBM 的 MPI 版本

  • MS MPIVisual Studio

  • MS MPICMakeVS Build Tools

注意:由于缺少 MPI 库,不支持使用 MinGW 构建 MPI 版本。

使用 GUI

  1. 您首先需要安装 MS MPImsmpisdk.msimsmpisetup.exe 都需要。

  2. 安装 Visual Studio

  3. 导航到 https://github.com/microsoft/LightGBM/releases 的某个发布版本,下载 LightGBM-complete_source_code_zip.zip,然后解压。

  4. 前往 LightGBM-complete_source_code_zip/windows 文件夹。

  5. 使用 Visual Studio 打开 LightGBM.sln 文件,选择 Release_mpi 配置,然后点击 Build -> Build Solution (Ctrl+Shift+B)

    如果出现关于 Platform Toolset 的错误,请前往 Project -> Properties -> Configuration Properties -> General 并选择机器上已安装的工具集。

.exe 文件将在 LightGBM-complete_source_code_zip/windows/x64/Release_mpi 文件夹中。

通过命令行

  1. 您首先需要安装 MS MPImsmpisdk.msimsmpisetup.exe 都需要。

  2. 安装 Git for WindowsCMakeVS Build Tools(如果已安装 Visual Studio,则不需要 VS Build Tools)。

  3. 运行以下命令

    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
    

.exe.dll 文件将在 LightGBM/Release 文件夹中。

Linux

在 Linux 上,可以使用以下方式构建 LightGBM 的 MPI 版本

  • CMakegccOpen MPI

  • CMakeClangOpen MPI

编译后,可执行文件和 .so 文件将在 LightGBM/ 文件夹中。

gcc

  1. 安装 CMakegccOpen MPI

  2. 运行以下命令

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

Clang

  1. 安装 CMakeClangOpenMPOpen MPI

  2. 运行以下命令

    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
    

macOS

在 macOS 上,可以使用以下方式构建 LightGBM 的 MPI 版本

  • CMakeOpen MPIApple Clang

  • CMakeOpen MPIgcc

编译后,可执行文件和 .dylib 文件将在 LightGBM/ 文件夹中。

Apple Clang

  1. 安装 CMakeOpenMPOpen MPI

    brew install cmake libomp open-mpi
    
  2. 运行以下命令

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

gcc

  1. 安装 CMakeOpen MPIgcc

    brew install cmake open-mpi gcc
    
  2. 运行以下命令

    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
    

构建 GPU 版本

Windows

在 Windows 上,可以使用以下方式构建 LightGBM 的 GPU 版本 (device_type=gpu)

  • OpenCLBoostCMakeVS Build Tools

  • OpenCLBoostCMakeMinGW

如果您使用 MinGW,构建过程与在 Linux 上构建类似。

以下过程适用于 MSVC (Microsoft Visual C++) 构建。

  1. 安装 Git for WindowsCMakeVS Build Tools(如果已安装 Visual Studio,则不需要 VS Build Tools)。

  2. 安装适用于 Windows 的 OpenCL。安装取决于您的 GPU 显卡的品牌 (NVIDIA, AMD, Intel)。

    • 对于在 Intel 上运行,获取 Intel SDK for OpenCL

    • 对于在 AMD 上运行,获取 AMD APP SDK。

    • 对于在 NVIDIA 上运行,获取 CUDA Toolkit

    进一步阅读和对应表:GPU SDK 对应和设备目标表

  3. 安装 Boost 二进制文件

    注意:匹配您的 Visual C++ 版本

    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

  4. 运行以下命令

    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
    

    注意C:/local/boost_1_63_0C:/local/boost_1_63_0/lib64-msvc-14.0 是您的 Boost 二进制文件的位置(假设您下载了适用于 Visual Studio 2015 的 1.63.0 版本)。

.exe.dll 文件将在 LightGBM/Release 文件夹中。

Linux

在 Linux 上,可以使用以下方式构建 LightGBM 的 GPU 版本 (device_type=gpu)

  • CMakeOpenCLBoostgcc

  • CMakeOpenCLBoostClang

通常由 GPU 制造商提供 OpenCL 头文件和库。也可以使用通用 OpenCL ICD 包(例如,Debian 包 ocl-icd-libopencl1ocl-icd-opencl-devpocl-opencl-icd)。

所需的 Boost 库(Boost.Align、Boost.System、Boost.Filesystem、Boost.Chrono)应由以下 Debian 包提供:libboost-devlibboost-system-devlibboost-filesystem-devlibboost-chrono-dev

编译后,可执行文件和 .so 文件将在 LightGBM/ 文件夹中。

gcc

  1. 安装 CMakegccOpenCLBoost

  2. 运行以下命令

    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

  1. 安装 CMakeClangOpenMPOpenCLBoost

  2. 运行以下命令

    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

macOS 不支持 GPU 版本。

Docker

请参考 GPU Docker 文件夹

构建 CUDA 版本

LightGBM 的原始 GPU 版本 (device_type=gpu) 基于 OpenCL。

基于 CUDA 的版本 (device_type=cuda) 是一个独立的实现。在具有计算能力 6.0 或更高版本的 NVIDIA GPU 的 Linux 环境中使用此版本。

Windows

Windows 不支持 CUDA 版本。在 Windows 上使用GPU 版本 (device_type=gpu) 进行 GPU 加速。

Linux

在 Linux 上,可以使用以下方式构建 LightGBM 的 CUDA 版本

  • CMakegccCUDA

  • CMakeClangCUDA

有关 CUDA 库安装的详细信息,请参考此详细指南

编译后,可执行文件和 .so 文件将在 LightGBM/ 文件夹中。

gcc

  1. 安装 CMakegccCUDA

  2. 运行以下命令

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

Clang

  1. 安装 CMakeClangOpenMPCUDA

  2. 运行以下命令

    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

macOS 不支持 CUDA 版本。

构建 Java Wrapper

使用以下说明,您可以生成一个 JAR 文件,其中包含由 SWIG 包装的 LightGBM C API

编译后,.jar 文件将在 LightGBM/build 文件夹中。

Windows

在 Windows 上,可以使用以下方式构建 LightGBM 的 Java wrapper

  • JavaSWIGCMakeVS Build Tools

  • JavaSWIGCMakeMinGW

VS Build Tools

  1. 安装 Git for WindowsCMakeVS Build Tools(如果已安装 Visual Studio,则不需要 VS Build Tools)。

  2. 安装 SWIGJava(并确保正确设置了 JAVA_HOME 环境变量)。

  3. 运行以下命令

    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

  1. 安装 Git for WindowsCMakeMinGW-w64

  2. 安装 SWIGJava(并确保正确设置了 JAVA_HOME 环境变量)。

  3. 运行以下命令

    git clone --recursive https://github.com/microsoft/LightGBM
    cd LightGBM
    cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON
    cmake --build build -j4
    

注意:如果遇到 sh.exe was found in your PATH 错误,您可能需要再次运行 cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON 或将 -DCMAKE_SH=CMAKE_SH-NOTFOUND 添加到 CMake 标志。

建议使用 VS Build Tools (Visual Studio),因为它在 Windows 多核系统上具有更好的多线程效率(请参阅问题 4问题 8)。

Linux

在 Linux 上,可以使用以下方式构建 LightGBM 的 Java wrapper

  • CMakegccJavaSWIG

  • CMakeClangJavaSWIG

gcc

  1. 安装 CMakegccSWIGJava(并确保正确设置了 JAVA_HOME 环境变量)。

  2. 运行以下命令

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

Clang

  1. 安装 CMakeClangOpenMPSWIGJava(并确保正确设置了 JAVA_HOME 环境变量)。

  2. 运行以下命令

    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

在 macOS 上,可以使用以下方式构建 LightGBM 的 Java wrapper

  • CMakeJavaSWIGApple Clang

  • CMakeJavaSWIGgcc

Apple Clang

  1. 安装 CMakeJava(并确保正确设置了 JAVA_HOME 环境变量)、SWIGOpenMP

    brew install cmake openjdk swig libomp
    export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
    
  2. 运行以下命令

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

gcc

  1. 安装 CMakeJava(并确保正确设置了 JAVA_HOME 环境变量)、SWIGgcc

    brew install cmake openjdk swig gcc
    export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
    
  2. 运行以下命令

    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
    

构建 Python 包

请参考 Python 包文件夹

构建 R 包

请参考 R 包文件夹

构建 C++ 单元测试

Windows

在 Windows 上,可以使用以下方式构建 LightGBM 的 C++ 单元测试

  • CMakeVS Build Tools

  • CMakeMinGW

VS Build Tools

  1. 安装 Git for WindowsCMakeVS Build Tools(如果已安装 Visual Studio,则不需要 VS Build Tools)。

  2. 运行以下命令

    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
    

.exe 文件将在 LightGBM/Debug 文件夹中。

MinGW-w64

  1. 安装 Git for WindowsCMakeMinGW-w64

  2. 运行以下命令

    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
    

.exe 文件将在 LightGBM/ 文件夹中。

注意:如果遇到 sh.exe was found in your PATH 错误,您可能需要再次运行 cmake -B build -S . -G "MinGW Makefiles" -DBUILD_CPP_TEST=ON 或将 -DCMAKE_SH=CMAKE_SH-NOTFOUND 添加到 CMake 标志。

Linux

在 Linux 上,可以使用以下方式构建 LightGBM 的 C++ 单元测试

  • CMakegcc

  • CMakeClang

编译后,可执行文件将在 LightGBM/ 文件夹中。

gcc

  1. 安装 CMakegcc

  2. 运行以下命令

    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

  1. 安装 CMakeClangOpenMP

  2. 运行以下命令

    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

在 macOS 上,可以使用以下方式构建 LightGBM 的 C++ 单元测试

  • CMakeApple Clang

  • CMakegcc

编译后,可执行文件将在 LightGBM/ 文件夹中。

Apple Clang

  1. 安装 CMakeOpenMP

    brew install cmake libomp
    
  2. 运行以下命令

    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

  1. 安装 CMakegcc

    brew install cmake gcc
    
  2. 运行以下命令

    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