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

4
This is a guide for building the LightGBM Command Line Interface (CLI). If you want to build the Python-package or R-package please refer to `Python-package`_ and `R-package`_ folders respectively.
5

6
7
8
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.
9

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

12
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
13

14
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
15

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
.. _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.

31
32
.. _nightly-builds:

33
You can also download the artifacts of the latest successful build on master branch (nightly builds) here: |download artifacts|.
34

35
36
37
38
.. contents:: **Contents**
    :depth: 1
    :local:
    :backlinks: none
39

40
41
42
Windows
~~~~~~~

43
44
45
46
On Windows LightGBM can be built using

- **Visual Studio**;

47
- **CMake** and **VS Build Tools**;
48
49

- **CMake** and **MinGW**.
50

51
52
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53
54
55
56

With GUI
********

57
1. Install `Visual Studio`_ (2015 or newer).
58
59
60
61
62

2. Download `zip archive`_ and unzip it.

3. Go to ``LightGBM-master/windows`` folder.

63
4. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.
64

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

67
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
68
69
70
71

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

72
1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
73
74
75
76
77

2. Run the following commands:

   .. code::

78
     git clone --recursive https://github.com/microsoft/LightGBM
79
80
81
     cd LightGBM
     mkdir build
     cd build
82
     cmake -A x64 ..
83
84
     cmake --build . --target ALL_BUILD --config Release

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

87
88
MinGW-w64
^^^^^^^^^
89
90
91
92
93
94
95

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

2. Run the following commands:

   .. code::

96
     git clone --recursive https://github.com/microsoft/LightGBM
97
98
99
100
101
102
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" ..
     mingw32-make.exe -j4

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

105
**Note**: You may need to run the ``cmake -G "MinGW Makefiles" ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.
106

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

Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
111

112
113
114
Linux
~~~~~

115
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
116

117
1. Install `CMake`_.
118

119
120
121
122
2. Run the following commands:

   .. code::

123
124
125
126
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
127
128
     cmake ..
     make -j4
129
130
131

**Note**: glibc >= 2.14 is required.

132
Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
133

134
135
macOS
~~~~~
136

137
On macOS LightGBM can be installed using **Homebrew**, or can be built using **CMake** and **Apple Clang** or **gcc**.
138
139
140

Apple Clang
^^^^^^^^^^^
fanliwen's avatar
fanliwen committed
141

142
Only **Apple Clang** version 8.1 or higher is supported.
fanliwen's avatar
fanliwen committed
143

144
145
146
147
148
149
150
151
152
153
Install Using ``Homebrew``
**************************

.. code::

  brew install lightgbm

Build from GitHub
*****************

154
1. Install `CMake`_ (3.16 or higher):
Nikita Titov's avatar
Nikita Titov committed
155

156
   .. code::
Nikita Titov's avatar
Nikita Titov committed
157

158
     brew install cmake
fanliwen's avatar
fanliwen committed
159

160
2. Install **OpenMP**:
fanliwen's avatar
fanliwen committed
161
162
163
164

   .. code::

     brew install libomp
165
166
167
168
169

3. Run the following commands:

   .. code::

170
171
172
173
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
fanliwen's avatar
fanliwen committed
174
175
176
     cmake ..
     make -j4

177
178
gcc
^^^
179

180
1. Install `CMake`_ (3.2 or higher):
181

182
   .. code::
183

184
     brew install cmake
185

186
2. Install **gcc**:
187

188
   .. code::
189

190
191
192
193
194
195
     brew install gcc

3. Run the following commands:

   .. code::

196
197
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
198
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
199
200
     mkdir build
     cd build
201
202
     cmake ..
     make -j4
203

204
Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
205

206
207
208
Docker
~~~~~~

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

211
212
213
214
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default build version of LightGBM is based on OpenMP.
215
You can build LightGBM without OpenMP support but it is **strongly not recommended**.
216
217
218
219

Windows
^^^^^^^

220
On Windows a version of LightGBM without OpenMP support can be built using
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

- **Visual Studio**;

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

- **CMake** and **MinGW**.

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

With GUI
--------

1. Install `Visual Studio`_ (2015 or newer).

2. Download `zip archive`_ and unzip it.

3. Go to ``LightGBM-master/windows`` folder.

4. Open ``LightGBM.sln`` file with **Visual Studio**.

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

6. Get back to the project's main screen, then choose ``Release`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.

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

248
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
249
250
251
252
253
254
255
256
257
258

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

1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).

2. Run the following commands:

   .. code::

259
     git clone --recursive https://github.com/microsoft/LightGBM
260
261
262
     cd LightGBM
     mkdir build
     cd build
263
     cmake -A x64 -DUSE_OPENMP=OFF ..
264
265
     cmake --build . --target ALL_BUILD --config Release

266
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
267
268
269
270
271
272
273
274
275
276

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

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

2. Run the following commands:

   .. code::

277
     git clone --recursive https://github.com/microsoft/LightGBM
278
279
280
281
282
283
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..
     mingw32-make.exe -j4

284
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
285
286
287
288
289
290

**Note**: You may need to run the ``cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.

Linux
^^^^^

291
On Linux a version of LightGBM without OpenMP support can be built using **CMake** and **gcc** or **Clang**.
292
293
294
295
296
297
298

1. Install `CMake`_.

2. Run the following commands:

   .. code::

299
300
301
302
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
303
304
305
306
307
308
309
310
     cmake -DUSE_OPENMP=OFF ..
     make -j4

**Note**: glibc >= 2.14 is required.

macOS
^^^^^

311
On macOS a version of LightGBM without OpenMP support can be built using **CMake** and **Apple Clang** or **gcc**.
312
313
314
315
316
317

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

Only **Apple Clang** version 8.1 or higher is supported.

318
1. Install `CMake`_ (3.16 or higher):
319
320
321
322
323
324
325
326
327

   .. code::

     brew install cmake

2. Run the following commands:

   .. code::

328
329
330
331
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
     cmake -DUSE_OPENMP=OFF ..
     make -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Run the following commands:

   .. code::

354
355
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
356
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
357
358
     mkdir build
     cd build
359
360
361
     cmake -DUSE_OPENMP=OFF ..
     make -j4

362
363
364
Build MPI Version
~~~~~~~~~~~~~~~~~

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

368
If you need to run a distributed learning application with high performance communication, you can build the LightGBM with MPI support.
369
370
371
372

Windows
^^^^^^^

373
On Windows an MPI version of LightGBM can be built using
374
375
376

- **MS MPI** and **Visual Studio**;

377
- **MS MPI**, **CMake** and **VS Build Tools**.
378

379
380
381
With GUI
********

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

384
2. Install `Visual Studio`_ (2015 or newer).
385
386
387
388
389

3. Download `zip archive`_ and unzip it.

4. Go to ``LightGBM-master/windows`` folder.

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

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

394
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.
395
396
397
398

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

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

401
2. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
402
403
404
405
406

3. Run the following commands:

   .. code::

407
     git clone --recursive https://github.com/microsoft/LightGBM
408
409
410
     cd LightGBM
     mkdir build
     cd build
411
     cmake -A x64 -DUSE_MPI=ON ..
412
413
     cmake --build . --target ALL_BUILD --config Release

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

416
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
417
418
419
420

Linux
^^^^^

421
On Linux an MPI version of LightGBM can be built using **Open MPI**, **CMake** and **gcc** or **Clang**.
422

423
1. Install `Open MPI`_.
424

425
2. Install `CMake`_.
426

427
428
429
430
3. Run the following commands:

   .. code::

431
432
433
434
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
435
436
     cmake -DUSE_MPI=ON ..
     make -j4
437
438
439

**Note**: glibc >= 2.14 is required.

440
441
macOS
^^^^^
442

443
On macOS an MPI version of LightGBM can be built using **Open MPI**, **CMake** and **Apple Clang** or **gcc**.
444

445
446
Apple Clang
***********
447

448
Only **Apple Clang** version 8.1 or higher is supported.
449

450
1. Install `CMake`_ (3.16 or higher):
451

452
   .. code::
453

454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
     brew install cmake

2. Install **OpenMP**:

   .. code::

     brew install libomp

3. Install **Open MPI**:

   .. code::

     brew install open-mpi

4. Run the following commands:

   .. code::

472
473
474
475
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
     cmake -DUSE_MPI=ON ..
     make -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Install **Open MPI**:

   .. code::

     brew install open-mpi

4. Run the following commands:

   .. code::

504
505
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
506
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
507
508
     mkdir build
     cd build
509
510
     cmake -DUSE_MPI=ON ..
     make -j4
511
512
513
514
515
516
517

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

Linux
^^^^^

518
On Linux a GPU version of LightGBM (``device_type=gpu``) can be built using **OpenCL**, **Boost**, **CMake** and **gcc** or **Clang**.
519

520
521
The following dependencies should be installed before compilation:

522
-  **OpenCL** 1.2 headers and libraries, which is usually provided by GPU manufacture.
523

524
   The generic OpenCL ICD packages (for example, Debian package ``ocl-icd-libopencl1`` and ``ocl-icd-opencl-dev``) can also be used.
525

526
-  **libboost** 1.56 or later (1.61 or later is recommended).
527
528
529
530
531

   We use Boost.Compute as the interface to GPU, which is part of the Boost library since version 1.61. However, since we include the source code of Boost.Compute as a submodule, we only require the host has Boost 1.56 or later installed. We also use Boost.Align for memory allocation. Boost.Compute requires Boost.System and Boost.Filesystem to store offline kernel cache.

   The following Debian packages should provide necessary Boost libraries: ``libboost-dev``, ``libboost-system-dev``, ``libboost-filesystem-dev``.

532
-  **CMake** 3.2 or later.
533
534
535
536
537

To build LightGBM GPU version, run the following commands:

.. code::

538
539
540
541
  git clone --recursive https://github.com/microsoft/LightGBM
  cd LightGBM
  mkdir build
  cd build
542
  cmake -DUSE_GPU=1 ..
543
544
  # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
  # cmake -DUSE_GPU=1 -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/ ..
545
546
547
548
549
  make -j4

Windows
^^^^^^^

550
On Windows a GPU version of LightGBM (``device_type=gpu``) can be built using **OpenCL**, **Boost**, **CMake** and **VS Build Tools** or **MinGW**.
551

552
If you use **MinGW**, the build procedure is similar to the build on Linux. Refer to `GPU Windows Compilation <./GPU-Windows.rst>`__ to get more details.
553

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

556
1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is installed).
557
558
559
560
561

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

562
   - For running on AMD, get AMD APP SDK.
563
564
565

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

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

Nikita Titov's avatar
Nikita Titov committed
568
3. Install `Boost Binaries`_.
569

570
   **Note**: Match your Visual C++ version:
571
572
573
   
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

574
575
576
   Visual Studio 2017 -> ``msvc-14.1-64.exe``,

   Visual Studio 2019 -> ``msvc-14.2-64.exe``.
577
578
579
580
581

4. Run the following commands:

   .. code::

582
     git clone --recursive https://github.com/microsoft/LightGBM
583
584
585
     cd LightGBM
     mkdir build
     cd build
586
587
588
     cmake -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 -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" ..
589
590
     cmake --build . --target ALL_BUILD --config Release

591
   **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).
592
593
594
595

Docker
^^^^^^

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

598
599
600
Build CUDA Version (Experimental)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

603
The CUDA-based build (``device_type=cuda``) is a separate implementation and requires an NVIDIA graphics card with compute capability 6.0 and higher. It should be considered experimental, and we suggest using it only when it is impossible to use OpenCL version (for example, on IBM POWER microprocessors).
604
605
606
607
608
609

**Note**: only Linux is supported, other operating systems are not supported yet.

Linux
^^^^^

610
On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc** or **Clang**.
611
612
613

The following dependencies should be installed before compilation:

614
-  **CUDA** 9.0 or later libraries. Please refer to `this detailed guide`_. Pay great attention to the minimum required versions of host compilers listed in the table from that guide and use only recommended versions of compilers.
615
616
617
618
619
620
621

-  **CMake** 3.16 or later.

To build LightGBM CUDA version, run the following commands:

.. code::

622
623
624
625
  git clone --recursive https://github.com/microsoft/LightGBM
  cd LightGBM
  mkdir build
  cd build
626
627
628
  cmake -DUSE_CUDA=1 ..
  make -j4

629
630
631
Build HDFS Version
~~~~~~~~~~~~~~~~~~

632
The HDFS version of LightGBM was tested on CDH-5.14.4 cluster.
633
634
635
636

Linux
^^^^^

637
On Linux a HDFS version of LightGBM can be built using **CMake** and **gcc**.
638

639
1. Install `CMake`_.
fanliwen's avatar
fanliwen committed
640
641
642
643
644

2. Run the following commands:

   .. code::

645
646
647
648
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
fanliwen's avatar
fanliwen committed
649
     cmake -DUSE_HDFS=ON ..
650
651
652
653
654
655
     # if you have installed HDFS to a customized location, you should specify paths to HDFS headers (hdfs.h) and library (libhdfs.so) like the following:
     # cmake \
     #   -DUSE_HDFS=ON \
     #   -DHDFS_LIB="/opt/cloudera/parcels/CDH-5.14.4-1.cdh5.14.4.p0.3/lib64/libhdfs.so" \
     #   -DHDFS_INCLUDE_DIR="/opt/cloudera/parcels/CDH-5.14.4-1.cdh5.14.4.p0.3/include/" \
     #   ..
fanliwen's avatar
fanliwen committed
656
657
     make -j4

658
659
660
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

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

Windows
^^^^^^^

666
On Windows a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **VS Build Tools** or **MinGW**.
667

668
669
VS Build Tools
**************
670

671
1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
672
673
674
675
676
677
678

2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).

3. Run the following commands:

   .. code::

679
     git clone --recursive https://github.com/microsoft/LightGBM
680
681
682
     cd LightGBM
     mkdir build
     cd build
683
     cmake -A x64 -DUSE_SWIG=ON ..
684
685
     cmake --build . --target ALL_BUILD --config Release

686
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/Release`` folder.
687
688
689
690
691
692
693
694
695
696
697
698

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

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

2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).

3. Run the following commands:

   .. code::

699
     git clone --recursive https://github.com/microsoft/LightGBM
700
701
702
703
704
705
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..
     mingw32-make.exe -j4

706
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/`` folder.
707
708
709

**Note**: You may need to run the ``cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.

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

713
714
Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.

715
716
717
Linux
^^^^^

718
On Linux a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **gcc** or **Clang**.
719

720
1. Install `CMake`_, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
721

722
2. Run the following commands:
723

724
725
   .. code::

726
727
728
729
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
730
     cmake -DUSE_SWIG=ON ..
731
     make -j4
732

733
734
735
macOS
^^^^^

736
On macOS a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **Apple Clang** or **gcc**.
737
738
739
740
741
742
743
744
745

First, install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
Then, either follow the **Apple Clang** or **gcc** installation instructions below.

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

Only **Apple Clang** version 8.1 or higher is supported.

746
1. Install `CMake`_ (3.16 or higher):
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761

   .. code::

     brew install cmake

2. Install **OpenMP**:

   .. code::

     brew install libomp

3. Run the following commands:

   .. code::

762
763
764
765
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
     cmake -DUSE_SWIG=ON -DAPPLE_OUTPUT_DYLIB=ON ..
     make -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Run the following commands:

   .. code::

788
789
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
790
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
791
792
     mkdir build
     cd build
793
794
795
796
797
     cmake -DUSE_SWIG=ON -DAPPLE_OUTPUT_DYLIB=ON ..
     make -j4

Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.

798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
Build C++ Unit Tests
~~~~~~~~~~~~~~~~~~~~

Windows
^^^^^^^

On Windows, C++ unit tests of LightGBM can be built using **CMake** and **VS Build Tools**.

1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -A x64 -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF ..
     cmake --build . --target testlightgbm --config Debug

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

Linux
^^^^^

On Linux a C++ unit tests of LightGBM can be built using **CMake** and **gcc** or **Clang**.

1. Install `CMake`_.

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF ..
     make testlightgbm -j4

**Note**: glibc >= 2.14 is required.

macOS
^^^^^

On macOS a C++ unit tests of LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.

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

Only **Apple Clang** version 8.1 or higher is supported.

1. Install `CMake`_ (3.16 or higher):

   .. code::

     brew install cmake

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF ..
     make testlightgbm -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
     mkdir build
     cd build
     cmake -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF ..
     make testlightgbm -j4

895

896
897
898
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

899
.. _Python-package: https://github.com/microsoft/LightGBM/tree/master/python-package
900

901
.. _R-package: https://github.com/microsoft/LightGBM/tree/master/R-package
902

903
.. _zip archive: https://github.com/microsoft/LightGBM/archive/master.zip
904

905
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
906
907
908
909
910

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

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

911
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
912
913
914
915
916
917
918

.. _MinGW-w64: https://mingw-w64.org/doku.php/download

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

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

919
.. _MS MPI: https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi-release-notes
920
921
922
923
924
925
926

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

927
.. _Boost Binaries: https://sourceforge.net/projects/boost/files/boost-binaries/
928
929

.. _SWIG: http://www.swig.org/download.html
930
931

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

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