Installation-Guide.rst 31.1 KB
Newer Older
1
2
3
Installation Guide
==================

4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
Versioning
~~~~~~~~~~

LightGBM releases use a 3-part version number, with this format:

.. code::

   {major}.{minor}.{patch}

This version follows a scheme called Intended Effort Versioning ("Effver" for short).
Changes to a component of the version indicate how much effort it will likely take to update
code using a previous version.

* ``major`` = updating will require significant effort
* ``minor`` = some effort
* ``patch`` = no or very little effort

This means that **new minor versions can contain breaking changes**, but these are typically
small or limited to less-frequently-used parts of the project.

When built from source on an unreleased commit, this version takes the following form:

.. code::

   {major}.{minor}.{patch}.99

That ``.99`` is added to ensure that a version built from an unreleased commit is considered "newer"
than all previous releases, and "older" than all future releases.

.. _nightly-builds:

You can find such artifacts from the latest successful build on the ``master`` branch (nightly builds) here: |download artifacts|.

For more details on why LightGBM uses EffVer instead of other schemes like semantic versioning,
see https://jacobtomlinson.dev/effver/.

General Installation Notes
~~~~~~~~~~~~~~~~~~~~~~~~~~

43
44
45
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.
46

47
48
49
50
51
52
53
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.

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

56
57
58
59
60
61
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.

62
Users who want to perform benchmarking can make LightGBM output time costs for different internal routines by adding ``-DUSE_TIMETAG=ON`` to CMake flags.
Guolin Ke's avatar
Guolin Ke committed
63

64
65
66
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.
Guolin Ke's avatar
Guolin Ke committed
67

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
.. _sanitizers:

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 <#build-c-unit-tests>`__ with sanitizers.

83
84
85
86
.. contents:: **Contents**
    :depth: 1
    :local:
    :backlinks: none
87

88
89
90
Windows
~~~~~~~

91
On Windows, LightGBM can be built using
92
93

- **Visual Studio**;
94
- **CMake** and **VS Build Tools**;
95
- **CMake** and **MinGW**.
96

97
98
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
99
100
101
102

With GUI
********

103
1. Install `Visual Studio`_.
104

105
2. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
106

107
3. Go to ``LightGBM-complete_source_code_zip/windows`` folder.
108

109
4. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release`` configuration if you need executable file or ``DLL`` configuration if you need shared library and click ``Build`` -> ``Build Solution (Ctrl+Shift+B)``.
110

111
   If you have errors about **Platform Toolset**, go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
112

113
114
   If you have errors about **Windows SDK Version**, go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the SDK installed on your machine.

115
116
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.
117
118
119
120

From Command Line
*****************

121
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
122
123
124

2. Run the following commands:

125
   .. code:: console
126

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

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

134
135
MinGW-w64
^^^^^^^^^
136
137
138
139
140

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

2. Run the following commands:

141
   .. code:: console
142

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

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

150
**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.
151

152
It is recommended that you use **Visual Studio** since it has better multithreading efficiency in **Windows** for many-core systems
153
(see `Question 4 <./FAQ.rst#i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__ and `Question 8 <./FAQ.rst#cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).
154

155
156
157
Linux
~~~~~

158
159
160
161
162
163
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.
164

165
166
167
168
gcc
^^^

1. Install `CMake`_ and **gcc**.
169

170
171
2. Run the following commands:

172
   .. code:: sh
173

174
175
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
176
177
     cmake -B build -S .
     cmake --build build -j4
178

179
180
Clang
^^^^^
181

182
1. Install `CMake`_, **Clang** and **OpenMP**.
183

184
2. Run the following commands:
185

186
   .. code:: sh
187
188
189

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
190
191
192
     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
193

194
195
macOS
~~~~~
196

197
On macOS, LightGBM can be installed using
198

199
200
201
202
- **Homebrew**;
- **MacPorts**;

or can be built using
fanliwen's avatar
fanliwen committed
203

204
205
- **CMake** and **Apple Clang**;
- **CMake** and **gcc**.
fanliwen's avatar
fanliwen committed
206

207
Install Using ``Homebrew``
208
^^^^^^^^^^^^^^^^^^^^^^^^^^
209

210
.. code:: sh
211
212
213

  brew install lightgbm

214
Refer to https://formulae.brew.sh/formula/lightgbm for more details.
215

216
217
Install Using ``MacPorts``
^^^^^^^^^^^^^^^^^^^^^^^^^^
Nikita Titov's avatar
Nikita Titov committed
218

219
.. code:: sh
Nikita Titov's avatar
Nikita Titov committed
220

221
222
223
224
225
  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.
fanliwen's avatar
fanliwen committed
226

227
228
229
230
231
232
233
234
235
Build from GitHub
^^^^^^^^^^^^^^^^^

After compilation the executable and ``.dylib`` files will be in ``LightGBM/`` folder.

Apple Clang
***********

1. Install `CMake`_ and **OpenMP**:
fanliwen's avatar
fanliwen committed
236

237
   .. code:: sh
fanliwen's avatar
fanliwen committed
238

239
     brew install cmake libomp
240

241
2. Run the following commands:
242

243
   .. code:: sh
244

245
246
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
247
248
     cmake -B build -S .
     cmake --build build -j4
fanliwen's avatar
fanliwen committed
249

250
gcc
251
***
252

253
1. Install `CMake`_ and **gcc**:
254

255
   .. code:: sh
256

257
     brew install cmake gcc
258

259
2. Run the following commands:
260

261
   .. code:: sh
262

263
264
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
265
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
266
267
     cmake -B build -S .
     cmake --build build -j4
268
269
270
271

Docker
~~~~~~

272
Refer to `Docker folder <https://github.com/microsoft/LightGBM/tree/master/docker>`__.
273

274
275
276
277
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default build version of LightGBM is based on OpenMP.
278
You can build LightGBM without OpenMP support but it is **strongly not recommended**.
279
280
281
282

Windows
^^^^^^^

283
On Windows, a version of LightGBM without OpenMP support can be built using
284
285
286
287
288
289
290
291
292
293
294

- **Visual Studio**;
- **CMake** and **VS Build Tools**;
- **CMake** and **MinGW**.

Visual Studio (or VS Build Tools)
*********************************

With GUI
--------

295
1. Install `Visual Studio`_.
296

297
2. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
298

299
3. Go to ``LightGBM-complete_source_code_zip/windows`` folder.
300

301
4. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release`` configuration if you need executable file or ``DLL`` configuration if you need shared library.
302

303
5. Go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``C/C++`` -> ``Language`` and change the ``OpenMP Support`` property to ``No (/openmp-)``.
304

305
6. Get back to the project's main screen and click ``Build`` -> ``Build Solution (Ctrl+Shift+B)``.
306

307
   If you have errors about **Platform Toolset**, go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
308

309
310
   If you have errors about **Windows SDK Version**, go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the SDK installed on your machine.

311
312
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.
313
314
315
316

From Command Line
-----------------

317
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
318
319
320

2. Run the following commands:

321
   .. code:: console
322

323
     git clone --recursive https://github.com/microsoft/LightGBM
324
     cd LightGBM
325
326
     cmake -B build -S . -A x64 -DUSE_OPENMP=OFF
     cmake --build build --target ALL_BUILD --config Release
327

328
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
329
330
331
332
333
334
335
336

MinGW-w64
*********

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

2. Run the following commands:

337
   .. code:: console
338

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

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

346
**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.
347
348
349
350

Linux
^^^^^

351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
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
***

1. Install `CMake`_ and **gcc**.

2. Run the following commands:

   .. code:: sh
366

367
368
369
370
371
372
373
374
375
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4

Clang
*****

1. Install `CMake`_ and **Clang**.
376
377
378

2. Run the following commands:

379
   .. code:: sh
380

381
382
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
383
     export CXX=clang++-14 CC=clang-14  # replace "14" with version of Clang installed on your machine
384
385
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4
386
387
388
389

macOS
^^^^^

390
391
392
393
394
395
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.
396
397
398
399

Apple Clang
***********

400
1. Install `CMake`_:
401

402
   .. code:: sh
403
404
405
406
407

     brew install cmake

2. Run the following commands:

408
   .. code:: sh
409

410
411
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
412
413
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4
414
415
416
417

gcc
***

418
1. Install `CMake`_ and **gcc**:
419

420
   .. code:: sh
421

422
     brew install cmake gcc
423

424
2. Run the following commands:
425

426
   .. code:: sh
427

428
429
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
430
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
431
432
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4
433

434
435
436
Build MPI Version
~~~~~~~~~~~~~~~~~

437
438
The default build version of LightGBM is based on socket. LightGBM also supports MPI.
`MPI`_ is a high performance communication approach with `RDMA`_ support.
439

440
If you need to run a distributed learning application with high performance communication, you can build the LightGBM with MPI support.
441
442
443
444

Windows
^^^^^^^

445
On Windows, an MPI version of LightGBM can be built using
446
447

- **MS MPI** and **Visual Studio**;
448
- **MS MPI**, **CMake** and **VS Build Tools**.
449

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

452
453
454
With GUI
********

455
1. You need to install `MS MPI`_ first. Both ``msmpisdk.msi`` and ``msmpisetup.exe`` are needed.
456

457
2. Install `Visual Studio`_.
458

459
3. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
460

461
4. Go to ``LightGBM-complete_source_code_zip/windows`` folder.
462

463
5. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release_mpi`` configuration and click ``Build`` -> ``Build Solution (Ctrl+Shift+B)``.
464

465
   If you have errors about **Platform Toolset**, go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
466

467
468
   If you have errors about **Windows SDK Version**, go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the SDK installed on your machine.

469
The ``.exe`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/Release_mpi`` folder.
470
471
472
473

From Command Line
*****************

474
1. You need to install `MS MPI`_ first. Both ``msmpisdk.msi`` and ``msmpisetup.exe`` are needed.
475

476
2. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
477
478
479

3. Run the following commands:

480
   .. code:: console
481

482
     git clone --recursive https://github.com/microsoft/LightGBM
483
     cd LightGBM
484
485
     cmake -B build -S . -A x64 -DUSE_MPI=ON
     cmake --build build --target ALL_BUILD --config Release
486

487
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
488
489
490
491

Linux
^^^^^

492
On Linux, an MPI version of LightGBM can be built using
493

494
495
- **CMake**, **gcc** and **Open MPI**;
- **CMake**, **Clang** and **Open MPI**.
496

497
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
498

499
500
501
502
503
504
gcc
***

1. Install `CMake`_, **gcc** and `Open MPI`_.

2. Run the following commands:
505

506
   .. code:: sh
507

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

513
514
Clang
*****
515

516
1. Install `CMake`_, **Clang**, **OpenMP** and `Open MPI`_.
517

518
2. Run the following commands:
519

520
   .. code:: sh
521

522
523
524
525
526
     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
527

528
529
macOS
^^^^^
530

531
On macOS, an MPI version of LightGBM can be built using
532

533
534
- **CMake**, **Open MPI** and **Apple Clang**;
- **CMake**, **Open MPI** and **gcc**.
535

536
After compilation the executable and ``.dylib`` files will be in ``LightGBM/`` folder.
537

538
539
Apple Clang
***********
540

541
1. Install `CMake`_, **OpenMP** and `Open MPI`_:
542

543
   .. code:: sh
544

545
     brew install cmake libomp open-mpi
546

547
2. Run the following commands:
548

549
   .. code:: sh
550

551
552
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
553
554
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
555
556
557
558

gcc
***

559
1. Install `CMake`_, `Open MPI`_ and  **gcc**:
560

561
   .. code:: sh
562

563
     brew install cmake open-mpi gcc
564

565
2. Run the following commands:
566

567
   .. code:: sh
568

569
570
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
571
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
572
573
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
574
575
576
577
578
579
580

Build GPU Version
~~~~~~~~~~~~~~~~~

Windows
^^^^^^^

581
582
583
584
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**.
585

586
If you use **MinGW**, the build procedure is similar to the build on Linux.
587

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

590
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is installed).
591
592
593
594
595

2. 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`_.

596
   - For running on AMD, get AMD APP SDK.
597
598
599

   - For running on NVIDIA, get `CUDA Toolkit`_.

600
601
   Further reading and correspondence table: `GPU SDK Correspondence and Device Targeting Table <./GPU-Targets.rst>`__.

Nikita Titov's avatar
Nikita Titov committed
602
3. Install `Boost Binaries`_.
603

604
   **Note**: Match your Visual C++ version:
605

606
607
   Visual Studio 2017 -> ``msvc-14.1-64.exe``,

608
609
610
   Visual Studio 2019 -> ``msvc-14.2-64.exe``,

   Visual Studio 2022 -> ``msvc-14.3-64.exe``.
611
612
613

4. Run the following commands:

614
   .. code:: console
615

616
     git clone --recursive https://github.com/microsoft/LightGBM
617
     cd LightGBM
618
     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.3
619
     # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
620
     # 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.3 -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"
621
     cmake --build build --target ALL_BUILD --config Release
622

623
   **Note**: ``C:/local/boost_1_63_0`` and ``C:/local/boost_1_63_0/lib64-msvc-14.3`` are locations of your **Boost** binaries (assuming you've downloaded 1.63.0 version for Visual Studio 2022).
624

625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
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
***

1. Install `CMake`_, **gcc**, **OpenCL** and **Boost**.

2. Run the following commands:

   .. code:: sh

     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. Install `CMake`_, **Clang**, **OpenMP**, **OpenCL** and **Boost**.

2. Run the following commands:

   .. code:: sh

     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.

680
681
682
Docker
^^^^^^

683
Refer to `GPU Docker folder <https://github.com/microsoft/LightGBM/tree/master/docker/gpu>`__.
684

685
686
Build CUDA Version
~~~~~~~~~~~~~~~~~~
687

688
The `original GPU version <#build-gpu-version>`__ of LightGBM (``device_type=gpu``) is based on OpenCL.
689

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

693
694
695
696
697
698
Windows
^^^^^^^

The CUDA version is not supported on Windows.
Use the `GPU version <#build-gpu-version>`__ (``device_type=gpu``) for GPU acceleration on Windows.

699
700
701
Linux
^^^^^

702
On Linux, a CUDA version of LightGBM can be built using
703

704
705
- **CMake**, **gcc** and **CUDA**;
- **CMake**, **Clang** and **CUDA**.
706

707
Please refer to `this detailed guide`_ for **CUDA** libraries installation.
708

709
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
710

711
712
gcc
***
713

714
715
716
1. Install `CMake`_, **gcc** and **CUDA**.

2. Run the following commands:
717

718
719
720
721
722
723
724
725
726
727
728
729
730
   .. code:: sh

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

Clang
*****

1. Install `CMake`_, **Clang**, **OpenMP** and **CUDA**.

2. Run the following commands:
731

732
733
734
735
736
737
738
   .. code:: sh

     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
739

740
741
742
743
744
macOS
^^^^^

The CUDA version is not supported on macOS.

745
746
747
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

748
Using the following instructions you can generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.
749

750
751
After compilation the ``.jar`` file will be in ``LightGBM/build`` folder.

752
753
754
Windows
^^^^^^^

755
756
757
758
On Windows, a Java wrapper of LightGBM can be built using

- **Java**, **SWIG**, **CMake** and **VS Build Tools**;
- **Java**, **SWIG**, **CMake** and **MinGW**.
759

760
761
VS Build Tools
**************
762

763
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
764

765
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
766
767
768

3. Run the following commands:

769
   .. code:: console
770

771
     git clone --recursive https://github.com/microsoft/LightGBM
772
     cd LightGBM
773
774
     cmake -B build -S . -A x64 -DUSE_SWIG=ON
     cmake --build build --target ALL_BUILD --config Release
775
776
777
778
779
780

MinGW-w64
*********

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

781
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
782
783
784

3. Run the following commands:

785
   .. code:: console
786

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

792
**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.
793

794
It is recommended to use **VS Build Tools (Visual Studio)** since it has better multithreading efficiency in **Windows** for many-core systems
795
796
(see `Question 4 <./FAQ.rst#i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__ and `Question 8 <./FAQ.rst#cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).

797
798
799
Linux
^^^^^

800
801
802
803
804
805
806
On Linux, a Java wrapper of LightGBM can be built using

- **CMake**, **gcc**, **Java** and **SWIG**;
- **CMake**, **Clang**, **Java** and **SWIG**.

gcc
***
807

808
1. Install `CMake`_, **gcc**, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
809

810
2. Run the following commands:
811

812
   .. code:: sh
813

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

819
820
Clang
*****
821

822
1. Install `CMake`_, **Clang**, **OpenMP**, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
823

824
2. Run the following commands:
825

826
   .. code:: sh
827

828
829
830
831
832
     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
833

834
835
macOS
^^^^^
836

837
On macOS, a Java wrapper of LightGBM can be built using
838

839
840
- **CMake**, **Java**, **SWIG** and **Apple Clang**;
- **CMake**, **Java**, **SWIG** and **gcc**.
841

842
843
Apple Clang
***********
844

845
1. Install `CMake`_, **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly), `SWIG`_ and **OpenMP**:
846

847
   .. code:: sh
848

849
850
     brew install cmake openjdk swig libomp
     export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
851

852
2. Run the following commands:
853

854
   .. code:: sh
855

856
857
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
858
     cmake -B build -S . -DUSE_SWIG=ON
859
     cmake --build build -j4
860
861
862
863

gcc
***

864
1. Install `CMake`_, **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly), `SWIG`_ and **gcc**:
865

866
   .. code:: sh
867

868
869
     brew install cmake openjdk swig gcc
     export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
870

871
2. Run the following commands:
872

873
   .. code:: sh
874

875
876
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
877
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
878
     cmake -B build -S . -DUSE_SWIG=ON
879
     cmake --build build -j4
880

881
882
883
884
885
886
887
888
889
890
Build Python-package
~~~~~~~~~~~~~~~~~~~~

Refer to `Python-package folder <https://github.com/microsoft/LightGBM/tree/master/python-package>`__.

Build R-package
~~~~~~~~~~~~~~~

Refer to `R-package folder <https://github.com/microsoft/LightGBM/tree/master/R-package>`__.

891
892
893
894
895
896
Build C++ Unit Tests
~~~~~~~~~~~~~~~~~~~~

Windows
^^^^^^^

897
898
899
900
901
902
903
On Windows, C++ unit tests of LightGBM can be built using

- **CMake** and **VS Build Tools**;
- **CMake** and **MinGW**.

VS Build Tools
**************
904

905
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
906
907
908

2. Run the following commands:

909
   .. code:: console
910
911
912

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
913
     cmake -B build -S . -A x64 -DBUILD_CPP_TEST=ON
914
     cmake --build build --target testlightgbm --config Debug
915
916
917

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

918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
MinGW-w64
*********

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

2. Run the following commands:

   .. code:: console

     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.

936
937
938
Linux
^^^^^

939
940
941
942
943
944
945
946
947
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
***
948

949
1. Install `CMake`_ and **gcc**.
950
951
952

2. Run the following commands:

953
   .. code:: sh
954
955
956

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
     cmake -B build -S . -DBUILD_CPP_TEST=ON
     cmake --build build --target testlightgbm -j4

Clang
*****

1. Install `CMake`_, **Clang** and **OpenMP**.

2. Run the following commands:

   .. code:: sh

     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
973
     cmake --build build --target testlightgbm -j4
974
975
976
977

macOS
^^^^^

978
979
980
981
982
983
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.
984
985
986
987

Apple Clang
***********

988
1. Install `CMake`_ and **OpenMP**:
989

990
   .. code:: sh
991

992
     brew install cmake libomp
993
994
995

2. Run the following commands:

996
   .. code:: sh
997
998
999

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
1000
     cmake -B build -S . -DBUILD_CPP_TEST=ON
1001
     cmake --build build --target testlightgbm -j4
1002
1003
1004
1005

gcc
***

1006
1. Install `CMake`_ and **gcc**:
1007

1008
   .. code:: sh
1009

1010
     brew install cmake gcc
1011

1012
2. Run the following commands:
1013

1014
   .. code:: sh
1015
1016
1017
1018

     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
1019
     cmake -B build -S . -DBUILD_CPP_TEST=ON
1020
     cmake --build build --target testlightgbm -j4
1021

1022

1023
1024
1025
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

1026
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
1027
1028
1029
1030
1031

.. _Git for Windows: https://git-scm.com/download/win

.. _CMake: https://cmake.org/

1032
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
1033

1034
.. _MinGW-w64: https://www.mingw-w64.org/downloads/
1035
1036
1037
1038
1039

.. _MPI: https://en.wikipedia.org/wiki/Message_Passing_Interface

.. _RDMA: https://en.wikipedia.org/wiki/Remote_direct_memory_access

1040
.. _MS MPI: https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi-release-notes
1041
1042
1043
1044
1045
1046
1047

.. _Open MPI: https://www.open-mpi.org/

.. _Intel SDK for OpenCL: https://software.intel.com/en-us/articles/opencl-drivers

.. _CUDA Toolkit: https://developer.nvidia.com/cuda-downloads

1048
.. _Boost Binaries: https://sourceforge.net/projects/boost/files/boost-binaries/
1049

James Lamb's avatar
James Lamb committed
1050
.. _SWIG: https://www.swig.org/download.html
1051
1052

.. _this detailed guide: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html
1053
1054

.. _following docs: https://github.com/google/sanitizers/wiki
1055
1056

.. _Ninja: https://ninja-build.org