Installation-Guide.rst 32.2 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
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.
115
116
117
118

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

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

2. Run the following commands:

123
   .. code:: console
124

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

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

132
133
MinGW-w64
^^^^^^^^^
134
135
136
137
138

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

2. Run the following commands:

139
   .. code:: console
140

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

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

148
**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.
149

150
It is recommended that you use **Visual Studio** since it has better multithreading efficiency in **Windows** for many-core systems
151
(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>`__).
152

153
154
155
Linux
~~~~~

156
157
158
159
160
161
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.
162

163
164
165
166
gcc
^^^

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

168
169
2. Run the following commands:

170
   .. code:: sh
171

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

177
178
Clang
^^^^^
179

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

182
2. Run the following commands:
183

184
   .. code:: sh
185
186
187

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

192
193
macOS
~~~~~
194

195
On macOS, LightGBM can be installed using
196

197
198
199
200
- **Homebrew**;
- **MacPorts**;

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

202
203
- **CMake** and **Apple Clang**;
- **CMake** and **gcc**.
fanliwen's avatar
fanliwen committed
204

205
Install Using ``Homebrew``
206
^^^^^^^^^^^^^^^^^^^^^^^^^^
207

208
.. code:: sh
209
210
211

  brew install lightgbm

212
Refer to https://formulae.brew.sh/formula/lightgbm for more details.
213

214
215
Install Using ``MacPorts``
^^^^^^^^^^^^^^^^^^^^^^^^^^
Nikita Titov's avatar
Nikita Titov committed
216

217
.. code:: sh
Nikita Titov's avatar
Nikita Titov committed
218

219
220
221
222
223
  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
224

225
226
227
228
229
230
231
232
233
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
234

235
   .. code:: sh
fanliwen's avatar
fanliwen committed
236

237
     brew install cmake libomp
238

239
2. Run the following commands:
240

241
   .. code:: sh
242

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

248
gcc
249
***
250

251
1. Install `CMake`_ and **gcc**:
252

253
   .. code:: sh
254

255
     brew install cmake gcc
256

257
2. Run the following commands:
258

259
   .. code:: sh
260

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

Docker
~~~~~~

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

272
273
274
275
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Windows
^^^^^^^

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

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

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

With GUI
--------

293
1. Install `Visual Studio`_.
294

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

297
3. Go to ``LightGBM-complete_source_code_zip/windows`` folder.
298

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

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

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

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

307
308
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.
309
310
311
312

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

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

2. Run the following commands:

317
   .. code:: console
318

319
     git clone --recursive https://github.com/microsoft/LightGBM
320
     cd LightGBM
321
322
     cmake -B build -S . -A x64 -DUSE_OPENMP=OFF
     cmake --build build --target ALL_BUILD --config Release
323

324
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
325
326
327
328
329
330
331
332

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

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

2. Run the following commands:

333
   .. code:: console
334

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

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

342
**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.
343
344
345
346

Linux
^^^^^

347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
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
362

363
364
365
366
367
368
369
370
371
     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**.
372
373
374

2. Run the following commands:

375
   .. code:: sh
376

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

macOS
^^^^^

386
387
388
389
390
391
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.
392
393
394
395

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

396
1. Install `CMake`_:
397

398
   .. code:: sh
399
400
401
402
403

     brew install cmake

2. Run the following commands:

404
   .. code:: sh
405

406
407
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
408
409
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4
410
411
412
413

gcc
***

414
1. Install `CMake`_ and **gcc**:
415

416
   .. code:: sh
417

418
     brew install cmake gcc
419

420
2. Run the following commands:
421

422
   .. code:: sh
423

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

430
431
432
Build MPI Version
~~~~~~~~~~~~~~~~~

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

436
If you need to run a distributed learning application with high performance communication, you can build the LightGBM with MPI support.
437
438
439
440

Windows
^^^^^^^

441
On Windows, an MPI version of LightGBM can be built using
442
443

- **MS MPI** and **Visual Studio**;
444
- **MS MPI**, **CMake** and **VS Build Tools**.
445

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

448
449
450
With GUI
********

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

453
2. Install `Visual Studio`_.
454

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

457
4. Go to ``LightGBM-complete_source_code_zip/windows`` folder.
458

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

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

463
The ``.exe`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/Release_mpi`` folder.
464
465
466
467

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

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

470
2. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
471
472
473

3. Run the following commands:

474
   .. code:: console
475

476
     git clone --recursive https://github.com/microsoft/LightGBM
477
     cd LightGBM
478
479
     cmake -B build -S . -A x64 -DUSE_MPI=ON
     cmake --build build --target ALL_BUILD --config Release
480

481
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
482
483
484
485

Linux
^^^^^

486
On Linux, an MPI version of LightGBM can be built using
487

488
489
- **CMake**, **gcc** and **Open MPI**;
- **CMake**, **Clang** and **Open MPI**.
490

491
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
492

493
494
495
496
497
498
gcc
***

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

2. Run the following commands:
499

500
   .. code:: sh
501

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

507
508
Clang
*****
509

510
1. Install `CMake`_, **Clang**, **OpenMP** and `Open MPI`_.
511

512
2. Run the following commands:
513

514
   .. code:: sh
515

516
517
518
519
520
     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
521

522
523
macOS
^^^^^
524

525
On macOS, an MPI version of LightGBM can be built using
526

527
528
- **CMake**, **Open MPI** and **Apple Clang**;
- **CMake**, **Open MPI** and **gcc**.
529

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

532
533
Apple Clang
***********
534

535
1. Install `CMake`_, **OpenMP** and `Open MPI`_:
536

537
   .. code:: sh
538

539
     brew install cmake libomp open-mpi
540

541
2. Run the following commands:
542

543
   .. code:: sh
544

545
546
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
547
548
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
549
550
551
552

gcc
***

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

555
   .. code:: sh
556

557
     brew install cmake open-mpi gcc
558

559
2. Run the following commands:
560

561
   .. code:: sh
562

563
564
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
565
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
566
567
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
568
569
570
571
572
573
574

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

Windows
^^^^^^^

575
576
577
578
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**.
579

580
If you use **MinGW**, the build procedure is similar to the build on Linux.
581

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

584
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is installed).
585
586
587
588
589

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

590
   - For running on AMD, get AMD APP SDK.
591
592
593

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

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

Nikita Titov's avatar
Nikita Titov committed
596
3. Install `Boost Binaries`_.
597

598
   **Note**: Match your Visual C++ version:
599

600
601
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

602
603
   Visual Studio 2017 -> ``msvc-14.1-64.exe``,

604
605
606
   Visual Studio 2019 -> ``msvc-14.2-64.exe``,

   Visual Studio 2022 -> ``msvc-14.3-64.exe``.
607
608
609

4. Run the following commands:

610
   .. code:: console
611

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

619
   **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).
620

621
622
623
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
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.

676
677
678
Docker
^^^^^^

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

681
682
Build CUDA Version
~~~~~~~~~~~~~~~~~~
683

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

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

689
690
691
692
693
694
Windows
^^^^^^^

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

695
696
697
Linux
^^^^^

698
On Linux, a CUDA version of LightGBM can be built using
699

700
701
- **CMake**, **gcc** and **CUDA**;
- **CMake**, **Clang** and **CUDA**.
702

703
Please refer to `this detailed guide`_ for **CUDA** libraries installation.
704

705
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
706

707
708
gcc
***
709

710
711
712
1. Install `CMake`_, **gcc** and **CUDA**.

2. Run the following commands:
713

714
715
716
717
718
719
720
721
722
723
724
725
726
   .. 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:
727

728
729
730
731
732
733
734
   .. 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
735

736
737
738
739
740
macOS
^^^^^

The CUDA version is not supported on macOS.

Jeff Daily's avatar
Jeff Daily committed
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
Build ROCm Version
~~~~~~~~~~~~~~~~~~

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

The ROCm-based version (``device_type=cuda``) is a separate implementation. Yes, the ROCm version reuses the ``device_type=cuda`` as a convenience for users.  Use this version in Linux environments with an AMD GPU.

Windows
^^^^^^^

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

Linux
^^^^^

On Linux, a ROCm version of LightGBM can be built using

- **CMake**, **gcc** and **ROCm**;
- **CMake**, **Clang** and **ROCm**.

Please refer to `the ROCm docs`_ for **ROCm** libraries installation.

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

gcc
***

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

2. Run the following commands:

   .. code:: sh

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

Clang
*****

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

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_ROCM=ON
     cmake --build build -j4

macOS
^^^^^

The ROCm version is not supported on macOS.

800
801
802
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

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

805
806
After compilation the ``.jar`` file will be in ``LightGBM/build`` folder.

807
808
809
Windows
^^^^^^^

810
811
812
813
On Windows, a Java wrapper of LightGBM can be built using

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

815
816
VS Build Tools
**************
817

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

820
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
821
822
823

3. Run the following commands:

824
   .. code:: console
825

826
     git clone --recursive https://github.com/microsoft/LightGBM
827
     cd LightGBM
828
829
     cmake -B build -S . -A x64 -DUSE_SWIG=ON
     cmake --build build --target ALL_BUILD --config Release
830
831
832
833
834
835

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

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

836
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
837
838
839

3. Run the following commands:

840
   .. code:: console
841

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

847
**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.
848

849
It is recommended to use **VS Build Tools (Visual Studio)** since it has better multithreading efficiency in **Windows** for many-core systems
850
851
(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>`__).

852
853
854
Linux
^^^^^

855
856
857
858
859
860
861
On Linux, a Java wrapper of LightGBM can be built using

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

gcc
***
862

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

865
2. Run the following commands:
866

867
   .. code:: sh
868

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

874
875
Clang
*****
876

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

879
2. Run the following commands:
880

881
   .. code:: sh
882

883
884
885
886
887
     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
888

889
890
macOS
^^^^^
891

892
On macOS, a Java wrapper of LightGBM can be built using
893

894
895
- **CMake**, **Java**, **SWIG** and **Apple Clang**;
- **CMake**, **Java**, **SWIG** and **gcc**.
896

897
898
Apple Clang
***********
899

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

902
   .. code:: sh
903

904
905
     brew install cmake openjdk swig libomp
     export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
906

907
2. Run the following commands:
908

909
   .. code:: sh
910

911
912
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
913
     cmake -B build -S . -DUSE_SWIG=ON
914
     cmake --build build -j4
915
916
917
918

gcc
***

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

921
   .. code:: sh
922

923
924
     brew install cmake openjdk swig gcc
     export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
925

926
2. Run the following commands:
927

928
   .. code:: sh
929

930
931
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
932
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
933
     cmake -B build -S . -DUSE_SWIG=ON
934
     cmake --build build -j4
935

936
937
938
939
940
941
942
943
944
945
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>`__.

946
947
948
949
950
951
Build C++ Unit Tests
~~~~~~~~~~~~~~~~~~~~

Windows
^^^^^^^

952
953
954
955
956
957
958
On Windows, C++ unit tests of LightGBM can be built using

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

VS Build Tools
**************
959

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

2. Run the following commands:

964
   .. code:: console
965
966
967

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
968
     cmake -B build -S . -A x64 -DBUILD_CPP_TEST=ON
969
     cmake --build build --target testlightgbm --config Debug
970
971
972

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

973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
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.

991
992
993
Linux
^^^^^

994
995
996
997
998
999
1000
1001
1002
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
***
1003

1004
1. Install `CMake`_ and **gcc**.
1005
1006
1007

2. Run the following commands:

1008
   .. code:: sh
1009
1010
1011

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
     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
1028
     cmake --build build --target testlightgbm -j4
1029
1030
1031
1032

macOS
^^^^^

1033
1034
1035
1036
1037
1038
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.
1039
1040
1041
1042

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

1043
1. Install `CMake`_ and **OpenMP**:
1044

1045
   .. code:: sh
1046

1047
     brew install cmake libomp
1048
1049
1050

2. Run the following commands:

1051
   .. code:: sh
1052
1053
1054

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
1055
     cmake -B build -S . -DBUILD_CPP_TEST=ON
1056
     cmake --build build --target testlightgbm -j4
1057
1058
1059
1060

gcc
***

1061
1. Install `CMake`_ and **gcc**:
1062

1063
   .. code:: sh
1064

1065
     brew install cmake gcc
1066

1067
2. Run the following commands:
1068

1069
   .. code:: sh
1070
1071
1072
1073

     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
1074
     cmake -B build -S . -DBUILD_CPP_TEST=ON
1075
     cmake --build build --target testlightgbm -j4
1076

1077

1078
1079
1080
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

1081
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
1082
1083
1084
1085
1086

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

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

1087
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
1088

1089
.. _MinGW-w64: https://www.mingw-w64.org/downloads/
1090
1091
1092
1093
1094

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

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

1095
.. _MS MPI: https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi-release-notes
1096
1097
1098
1099
1100
1101
1102

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

1103
.. _Boost Binaries: https://sourceforge.net/projects/boost/files/boost-binaries/
1104

James Lamb's avatar
James Lamb committed
1105
.. _SWIG: https://www.swig.org/download.html
1106
1107

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

Jeff Daily's avatar
Jeff Daily committed
1109
1110
.. _the ROCm docs: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/

1111
.. _following docs: https://github.com/google/sanitizers/wiki
1112
1113

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