安装指南

这是构建 LightGBM 命令行界面 (CLI) 的指南。如果你想构建 Python 包或 R 包，请分别参考 Python-package 和 R-package 文件夹。

以下所有指令旨在编译64位版本的LightGBM。只有在极少数涉及环境限制的特殊情况下，才值得编译32位版本。32位版本速度慢且未经测试，因此使用时需自行承担风险，并且在安装时不要忘记调整以下部分命令。

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

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

可以在调试模式下构建 LightGBM。在这种模式下，所有编译器优化都被禁用，并且 LightGBM 在内部执行更多检查。要启用调试模式，可以在 CMake 标志中添加 -DUSE_DEBUG=ON，或者在 Visual Studio 中选择 Debug_* 配置（例如 Debug_DLL，Debug_mpi），具体取决于你如何构建 LightGBM。

除了调试模式，LightGBM 还可以使用编译器 sanitizers 构建。要启用它们，请在 CMake 标志中添加 -DUSE_SANITIZER=ON -DENABLED_SANITIZERS="address;leak;undefined"。这些值指的是以下支持的 sanitizers：

address - AddressSanitizer (ASan);
leak - 内存泄漏检测器 (LSan);
undefined - 未定义行为清理器 (UBSan);
thread - ThreadSanitizer (TSan).

请注意，ThreadSanitizer 不能与其他 sanitizers 一起使用。更多信息和附加 sanitizers 的参数请参阅以下文档。使用 sanitizers 构建 C++ 单元测试非常有用。

您也可以在此下载主分支上最新成功构建的工件（夜间构建）：。

Windows

在 Windows 上，可以使用 LightGBM 进行构建。

Visual Studio;
CMake 和 VS Build Tools；
CMake 和 MinGW。

Visual Studio（或 VS Build Tools）

使用图形用户界面

安装 Visual Studio （2015 或更新版本）。
导航到 https://github.com/microsoft/LightGBM/releases 上的其中一个版本，下载 LightGBM-complete_source_code_zip.zip，并解压缩它。
进入 LightGBM-master/windows 文件夹。
使用 Visual Studio 打开 LightGBM.sln 文件，选择 Release 配置，然后点击 BUILD -> 生成解决方案 (Ctrl+Shift+B)。

如果你遇到关于 平台工具集 的错误，请转到 项目 -> 属性 -> 配置属性 -> 常规 并选择你机器上安装的工具集。

.exe 文件将在 LightGBM-master/windows/x64/Release 文件夹中。

从命令行

安装 Git for Windows、CMake 和 `VS Build Tools`_（如果已经安装了 Visual Studio**（2015 或更新版本），则不需要 **VS Build Tools）。

运行以下命令：

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

安装 Git for Windows、CMake 和 MinGW-w64。

运行以下命令：

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"。

建议您使用 Visual Studio，因为它在 Windows 上对多核系统具有更好的多线程效率（参见问题 4 和问题 8）。

Linux

在Linux上，LightGBM 可以使用 CMake 和 gcc 或 Clang 进行构建。

安装 CMake。

运行以下命令：

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

注意：在某些罕见情况下，您可能需要单独安装 OpenMP 运行时库（使用您的包管理器并搜索 lib[g|i]omp 来完成此操作）。

使用 `Ninja`

在Linux上，LightGBM 也可以使用 Ninja 而不是 make 来构建。

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

macOS

在 macOS 上，可以通过 Homebrew 安装 LightGBM，或者使用 CMake 和 Apple Clang 或 gcc 进行构建。

苹果 Clang

仅支持 Apple Clang 版本 8.1 或更高版本。

使用 `Homebrew` 安装

brew install lightgbm

从GitHub构建

安装 CMake :
```
brew install cmake
```
安装 OpenMP:
```
brew install libomp
```

运行以下命令：

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

gcc

安装 CMake :
```
brew install cmake
```
安装 gcc：
```
brew install gcc
```

运行以下命令：

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 文件夹。

构建无线程版本（不推荐）

LightGBM 的默认构建版本基于 OpenMP。你可以构建不支持 OpenMP 的 LightGBM，但这 强烈不推荐。

Windows

在Windows上，可以使用不支持OpenMP的LightGBM版本进行构建。

Visual Studio;
CMake 和 VS Build Tools；
CMake 和 MinGW。

Visual Studio（或 VS Build Tools）

使用图形用户界面

安装 Visual Studio （2015 或更新版本）。
导航到 https://github.com/microsoft/LightGBM/releases 上的其中一个版本，下载 LightGBM-complete_source_code_zip.zip，并解压缩它。
进入 LightGBM-master/windows 文件夹。
使用 Visual Studio 打开 LightGBM.sln 文件。
转到 PROJECT -> 属性 -> 配置属性 -> C/C++ -> 语言 并将 OpenMP 支持 属性更改为 否 (/openmp-)。
返回项目的主界面，然后选择 Release 配置并点击 BUILD -> 生成解决方案 (Ctrl+Shift+B)。

如果你遇到关于 平台工具集 的错误，请转到 项目 -> 属性 -> 配置属性 -> 常规 并选择你机器上安装的工具集。

.exe 文件将在 LightGBM-master/windows/x64/Release 文件夹中。

从命令行

安装 Git for Windows、CMake 和 `VS Build Tools`_（如果已经安装了 Visual Studio**（2015 或更新版本），则不需要 **VS Build Tools）。

运行以下命令：

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

.exe 和 .dll 文件将位于 LightGBM/Release 文件夹中。

MinGW-w64

安装 Git for Windows、CMake 和 MinGW-w64。

运行以下命令：

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

.exe 和 .dll 文件将位于 LightGBM/ 文件夹中。

注意: 如果你遇到 sh.exe was found in your PATH 错误，你可能需要再运行一次 cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF。

Linux

在Linux上，可以使用 CMake 和 gcc 或 Clang 构建一个不支持OpenMP的LightGBM版本。

安装 CMake。

运行以下命令：

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

macOS

在 macOS 上，可以使用 CMake 和 Apple Clang 或 gcc 构建一个不支持 OpenMP 的 LightGBM 版本。

苹果 Clang

仅支持 Apple Clang 版本 8.1 或更高版本。

安装 CMake :
```
brew install cmake
```

运行以下命令：

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

gcc

安装 CMake :
```
brew install cmake
```
安装 gcc：
```
brew install gcc
```

运行以下命令：

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

构建 MPI 版本

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

如果你需要运行一个高性能通信的分布式学习应用程序，你可以构建支持MPI的LightGBM。

Windows

在Windows上，可以使用MPI版本构建LightGBM。

MS MPI 和 Visual Studio；
MS MPI、CMake 和 VS Build Tools。

使用图形用户界面

您需要先安装 MS MPI。需要 msmpisdk.msi 和 msmpisetup.exe 两者。
安装 Visual Studio （2015 或更新版本）。
导航到 https://github.com/microsoft/LightGBM/releases 上的其中一个版本，下载 LightGBM-complete_source_code_zip.zip，并解压缩它。
进入 LightGBM-master/windows 文件夹。
使用 Visual Studio 打开 LightGBM.sln 文件，选择 Release_mpi 配置，然后点击 BUILD -> 生成解决方案 (Ctrl+Shift+B)。

如果你遇到关于 平台工具集 的错误，请转到 项目 -> 属性 -> 配置属性 -> 常规 并选择你机器上安装的工具集。

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

从命令行

您需要先安装 MS MPI。需要 msmpisdk.msi 和 msmpisetup.exe 两者。
安装 Git for Windows、CMake 和 `VS Build Tools`_（如果已经安装了 Visual Studio**（2015 或更新版本），则不需要 **VS Build Tools）。

运行以下命令：

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 文件夹中。

注意：由于缺少 MPI 库，不支持通过 MinGW 构建 MPI 版本。

Linux

在Linux上，可以使用 Open MPI、CMake 和 gcc 或 Clang 构建 LightGBM 的 MPI 版本。

安装 Open MPI。
安装 CMake。

运行以下命令：

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

注意：在某些罕见情况下，您可能需要单独安装 OpenMP 运行时库（使用您的包管理器并搜索 lib[g|i]omp 来完成此操作）。

macOS

在 macOS 上，可以使用 Open MPI、CMake 和 Apple Clang 或 gcc 构建 LightGBM 的 MPI 版本。

苹果 Clang

仅支持 Apple Clang 版本 8.1 或更高版本。

安装 CMake :
```
brew install cmake
```
安装 OpenMP:
```
brew install libomp
```
安装 Open MPI：
```
brew install open-mpi
```

运行以下命令：

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

gcc

安装 CMake :
```
brew install cmake
```
安装 gcc：
```
brew install gcc
```
安装 Open MPI：
```
brew install open-mpi
```

运行以下命令：

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 版本

Linux

在Linux上，可以使用 OpenCL、Boost、CMake 和 gcc 或 Clang 构建 LightGBM 的 GPU 版本 (device_type=gpu)。

以下依赖项应在编译前安装：

OpenCL 1.2 头文件和库，通常由 GPU 制造商提供。

通用 OpenCL ICD 包（例如，Debian 包 ocl-icd-libopencl1 和 ocl-icd-opencl-dev）也可以使用。
libboost 1.56 或更高版本（推荐使用 1.61 或更高版本）。

我们使用 Boost.Compute 作为 GPU 的接口，这是自 Boost 1.61 版本以来的 Boost 库的一部分。然而，由于我们将 Boost.Compute 的源代码作为子模块包含在内，我们只要求主机安装了 Boost 1.56 或更高版本。我们还使用 Boost.Align 进行内存分配。Boost.Compute 需要 Boost.System 和 Boost.Filesystem 来存储离线内核缓存。

以下 Debian 包应提供必要的 Boost 库：libboost-dev、libboost-system-dev、libboost-filesystem-dev。
CMake

要构建 LightGBM GPU 版本，请运行以下命令：

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

注意：在某些罕见情况下，您可能需要单独安装 OpenMP 运行时库（使用您的包管理器并搜索 lib[g|i]omp 来完成此操作）。

Windows

在Windows上，可以使用 OpenCL、Boost、CMake 和 VS Build Tools 或 MinGW 构建LightGBM的GPU版本（device_type=gpu）。

如果你使用 MinGW，构建过程与在 Linux 上的构建类似。

以下步骤适用于 MSVC (Microsoft Visual C++) 构建。

安装 Git for Windows、CMake 和 `VS Build Tools`_（如果已安装 Visual Studio**（2015 或更新版本），则不需要 **VS Build Tools）。
安装 OpenCL 用于 Windows。安装取决于您的 GPU 卡的品牌（NVIDIA、AMD、Intel）。
- 对于在Intel上运行，获取 Intel SDK for OpenCL。
- 对于在AMD上运行，获取AMD APP SDK。
- 要在 NVIDIA 上运行，请获取 CUDA Toolkit。
进一步阅读和对应表：GPU SDK 对应和设备目标表。
安装 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.

运行以下命令：

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

注意：C:/local/boost_1_63_0 和 C:/local/boost_1_63_0/lib64-msvc-14.0 是你的 Boost 二进制文件的位置（假设你已经为 Visual Studio 2015 下载了 1.63.0 版本）。

Docker

参考 GPU Docker 文件夹。

构建 CUDA 版本

LightGBM 的原始 GPU 构建 (device_type=gpu) 基于 OpenCL。

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

Linux

在 Linux 上，可以使用 CUDA、CMake 和 gcc 或 Clang 构建 LightGBM 的 CUDA 版本。

以下依赖项应在编译前安装：

CUDA 11.0 或更高版本的库。请参考这份详细指南。请特别注意该指南表格中列出的主机编译器的最低要求版本，并仅使用推荐的编译器版本。
CMake

要构建 LightGBM CUDA 版本，请运行以下命令：

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

注意：在某些罕见情况下，您可能需要单独安装 OpenMP 运行时库（使用您的包管理器并搜索 lib[g|i]omp 来完成此操作）。

macOS

CUDA 版本在 macOS 上不受支持。

Windows

CUDA 版本在 Windows 上不受支持。在 Windows 上使用 GPU 版本 (device_type=gpu) 以实现 GPU 加速。

构建 Java 包装器

使用以下指令，您可以生成一个包含 LightGBM C API 的 JAR 文件，该文件由 SWIG 封装。

Windows

在Windows上，可以使用 Java、SWIG、CMake 和 VS Build Tools 或 MinGW 构建 LightGBM 的 Java 包装器。

VS 构建工具

安装 Git for Windows、CMake 和 `VS Build Tools`_（如果已经安装了 Visual Studio**（2015 或更新版本），则不需要 **VS Build Tools）。
安装 SWIG 和 **Java**（同时确保 JAVA_HOME 设置正确）。

运行以下命令：

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

.jar 文件将在 LightGBM/build 文件夹中，而 .dll 文件将在 LightGBM/Release 文件夹中。

MinGW-w64

安装 Git for Windows、CMake 和 MinGW-w64。
安装 SWIG 和 **Java**（同时确保 JAVA_HOME 设置正确）。

运行以下命令：

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

.jar 文件将在 LightGBM/build 文件夹中，而 .dll 文件将在 LightGBM/ 文件夹中。

注意：如果你遇到 sh.exe was found in your PATH 错误，你可能需要再运行一次 cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON。

建议使用 VS Build Tools (Visual Studio)，因为它在多核系统（参见问题4 和问题8）的 Windows 系统中具有更好的多线程效率。

Linux

在Linux上，可以使用 Java、SWIG、CMake 和 gcc 或 Clang 构建 LightGBM 的 Java 封装。

安装 CMake、SWIG 和 **Java**（同时确保 JAVA_HOME 设置正确）。

运行以下命令：

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

注意：在某些罕见情况下，您可能需要单独安装 OpenMP 运行时库（使用您的包管理器并搜索 lib[g|i]omp 来完成此操作）。

macOS

在 macOS 上，可以使用 Java、SWIG、CMake 和 Apple Clang 或 gcc 构建 LightGBM 的 Java 包装器。

首先，安装 SWIG 和 Java**（同时确保 ``JAVA_HOME`` 设置正确）。然后，根据以下 **Apple Clang 或 gcc 的安装说明进行操作。

苹果 Clang

仅支持 Apple Clang 版本 8.1 或更高版本。

安装 CMake :
```
brew install cmake
```
安装 OpenMP:
```
brew install libomp
```

运行以下命令：

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

gcc

安装 CMake :
```
brew install cmake
```
安装 gcc：
```
brew install gcc
```

运行以下命令：

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

构建 C++ 单元测试

Windows

在Windows上，可以使用 CMake 和 VS Build Tools 构建 LightGBM 的 C++ 单元测试。

安装 Git for Windows、CMake 和 `VS Build Tools`_（如果已经安装了 Visual Studio**（2015 或更新版本），则不需要 **VS Build Tools）。

运行以下命令：

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

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

Linux

在Linux上，可以使用 CMake 和 gcc 或 Clang 构建 LightGBM 的 C++ 单元测试。

安装 CMake。

运行以下命令：

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

在 macOS 上，可以使用 CMake 和 Apple Clang 或 gcc 构建 LightGBM 的 C++ 单元测试。

苹果 Clang

仅支持 Apple Clang 版本 8.1 或更高版本。

安装 CMake :
```
brew install cmake
```

运行以下命令：

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

安装 CMake :
```
brew install cmake
```
安装 gcc：
```
brew install gcc
```

运行以下命令：

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

安装指南

Windows

Visual Studio（或 VS Build Tools）

使用图形用户界面

从命令行

MinGW-w64

Linux

使用 Ninja

macOS

苹果 Clang

使用 Homebrew 安装

从GitHub构建

gcc

Docker

构建无线程版本（不推荐）

Windows

Visual Studio（或 VS Build Tools）

使用图形用户界面

从命令行

MinGW-w64

Linux

macOS

苹果 Clang

gcc

构建 MPI 版本

Windows

使用图形用户界面

从命令行

Linux

macOS

苹果 Clang

gcc

构建 GPU 版本

Linux

Windows

Docker

构建 CUDA 版本

Linux

macOS

Windows

构建 Java 包装器

Windows

VS 构建工具

MinGW-w64

Linux

macOS

苹果 Clang

gcc

构建 C++ 单元测试

Windows

Linux

macOS

苹果 Clang

gcc

使用 `Ninja`

使用 `Homebrew` 安装