Installation-Guide.rst 24.8 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
.. _nightly-builds:

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

20
21
22
23
.. contents:: **Contents**
    :depth: 1
    :local:
    :backlinks: none
24

25
26
27
Windows
~~~~~~~

28
29
30
31
On Windows LightGBM can be built using

- **Visual Studio**;

32
- **CMake** and **VS Build Tools**;
33
34

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

36
37
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38
39
40
41

With GUI
********

42
1. Install `Visual Studio`_ (2015 or newer).
43
44
45
46
47

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

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

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

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

52
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
53
54
55
56

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

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

2. Run the following commands:

   .. code::

63
     git clone --recursive https://github.com/microsoft/LightGBM
64
65
66
     cd LightGBM
     mkdir build
     cd build
67
     cmake -A x64 ..
68
69
     cmake --build . --target ALL_BUILD --config Release

70
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
71

72
73
MinGW-w64
^^^^^^^^^
74
75
76
77
78
79
80

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

2. Run the following commands:

   .. code::

81
     git clone --recursive https://github.com/microsoft/LightGBM
82
83
84
85
86
87
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" ..
     mingw32-make.exe -j4

88
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
89

90
**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.
91

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

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

97
98
99
Linux
~~~~~

100
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
101

102
1. Install `CMake`_.
103

104
105
106
107
2. Run the following commands:

   .. code::

108
109
110
111
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
112
113
     cmake ..
     make -j4
114
115
116

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

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

119
120
macOS
~~~~~
121

122
On macOS LightGBM can be installed using **Homebrew**, or can be built using **CMake** and **Apple Clang** or **gcc**.
123
124
125

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

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

129
130
131
132
133
134
135
136
137
138
Install Using ``Homebrew``
**************************

.. code::

  brew install lightgbm

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

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

141
   .. code::
Nikita Titov's avatar
Nikita Titov committed
142

143
     brew install cmake
fanliwen's avatar
fanliwen committed
144

145
2. Install **OpenMP**:
fanliwen's avatar
fanliwen committed
146
147
148
149

   .. code::

     brew install libomp
150
151
152
153
154

3. Run the following commands:

   .. code::

155
156
157
158
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
fanliwen's avatar
fanliwen committed
159
160
161
     cmake ..
     make -j4

162
163
gcc
^^^
164

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

167
   .. code::
168

169
     brew install cmake
170

171
2. Install **gcc**:
172

173
   .. code::
174

175
176
177
178
179
180
     brew install gcc

3. Run the following commands:

   .. code::

181
182
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
183
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
184
185
     mkdir build
     cd build
186
187
     cmake ..
     make -j4
188

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

191
192
193
Docker
~~~~~~

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

196
197
198
199
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default build version of LightGBM is based on OpenMP.
200
You can build LightGBM without OpenMP support but it is **strongly not recommended**.
201
202
203
204

Windows
^^^^^^^

205
On Windows a version of LightGBM without OpenMP support can be built using
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232

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

233
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
234
235
236
237
238
239
240
241
242
243

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::

244
     git clone --recursive https://github.com/microsoft/LightGBM
245
246
247
     cd LightGBM
     mkdir build
     cd build
248
     cmake -A x64 -DUSE_OPENMP=OFF ..
249
250
     cmake --build . --target ALL_BUILD --config Release

251
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
252
253
254
255
256
257
258
259
260
261

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

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

2. Run the following commands:

   .. code::

262
     git clone --recursive https://github.com/microsoft/LightGBM
263
264
265
266
267
268
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..
     mingw32-make.exe -j4

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

**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
^^^^^

276
On Linux a version of LightGBM without OpenMP support can be built using **CMake** and **gcc** or **Clang**.
277
278
279
280
281
282
283

1. Install `CMake`_.

2. Run the following commands:

   .. code::

284
285
286
287
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
288
289
290
291
292
293
294
295
     cmake -DUSE_OPENMP=OFF ..
     make -j4

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

macOS
^^^^^

296
On macOS a version of LightGBM without OpenMP support can be built using **CMake** and **Apple Clang** or **gcc**.
297
298
299
300
301
302

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

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

303
1. Install `CMake`_ (3.16 or higher):
304
305
306
307
308
309
310
311
312

   .. code::

     brew install cmake

2. Run the following commands:

   .. code::

313
314
315
316
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
     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::

339
340
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
341
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
342
343
     mkdir build
     cd build
344
345
346
     cmake -DUSE_OPENMP=OFF ..
     make -j4

347
348
349
Build MPI Version
~~~~~~~~~~~~~~~~~

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

353
If you need to run a distributed learning application with high performance communication, you can build the LightGBM with MPI support.
354
355
356
357

Windows
^^^^^^^

358
On Windows an MPI version of LightGBM can be built using
359
360
361

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

362
- **MS MPI**, **CMake** and **VS Build Tools**.
363

364
365
366
With GUI
********

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

369
2. Install `Visual Studio`_ (2015 or newer).
370
371
372
373
374

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

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

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

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

379
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.
380
381
382
383

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

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

386
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).
387
388
389
390
391

3. Run the following commands:

   .. code::

392
     git clone --recursive https://github.com/microsoft/LightGBM
393
394
395
     cd LightGBM
     mkdir build
     cd build
396
     cmake -A x64 -DUSE_MPI=ON ..
397
398
     cmake --build . --target ALL_BUILD --config Release

399
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
400

401
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
402
403
404
405

Linux
^^^^^

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

408
1. Install `Open MPI`_.
409

410
2. Install `CMake`_.
411

412
413
414
415
3. Run the following commands:

   .. code::

416
417
418
419
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
420
421
     cmake -DUSE_MPI=ON ..
     make -j4
422
423
424

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

425
426
macOS
^^^^^
427

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

430
431
Apple Clang
***********
432

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

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

437
   .. code::
438

439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
     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::

457
458
459
460
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
     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::

489
490
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
491
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
492
493
     mkdir build
     cd build
494
495
     cmake -DUSE_MPI=ON ..
     make -j4
496
497
498
499
500
501
502

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

Linux
^^^^^

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

505
506
The following dependencies should be installed before compilation:

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

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

511
-  **libboost** 1.56 or later (1.61 or later is recommended).
512
513
514
515
516

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

517
-  **CMake** 3.2 or later.
518
519
520
521
522

To build LightGBM GPU version, run the following commands:

.. code::

523
524
525
526
  git clone --recursive https://github.com/microsoft/LightGBM
  cd LightGBM
  mkdir build
  cd build
527
  cmake -DUSE_GPU=1 ..
528
529
  # 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/ ..
530
531
532
533
534
  make -j4

Windows
^^^^^^^

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

537
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.
538

539
540
Following procedure is for the **MSVC** (Microsoft Visual C++) build.

541
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).
542
543
544
545
546

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

547
   - For running on AMD, get AMD APP SDK.
548
549
550

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

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

Nikita Titov's avatar
Nikita Titov committed
553
3. Install `Boost Binaries`_.
554

555
   **Note**: Match your Visual C++ version:
556
557
558
   
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

559
560
561
   Visual Studio 2017 -> ``msvc-14.1-64.exe``,

   Visual Studio 2019 -> ``msvc-14.2-64.exe``.
562
563
564
565
566

4. Run the following commands:

   .. code::

567
     git clone --recursive https://github.com/microsoft/LightGBM
568
569
570
     cd LightGBM
     mkdir build
     cd build
571
572
573
     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" ..
574
575
     cmake --build . --target ALL_BUILD --config Release

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

Docker
^^^^^^

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

583
584
585
Build CUDA Version (Experimental)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

588
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).
589
590
591
592
593
594

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

Linux
^^^^^

595
On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc** or **Clang**.
596
597
598

The following dependencies should be installed before compilation:

599
-  **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.
600
601
602
603
604
605
606

-  **CMake** 3.16 or later.

To build LightGBM CUDA version, run the following commands:

.. code::

607
608
609
610
  git clone --recursive https://github.com/microsoft/LightGBM
  cd LightGBM
  mkdir build
  cd build
611
612
613
  cmake -DUSE_CUDA=1 ..
  make -j4

614
615
616
Build HDFS Version
~~~~~~~~~~~~~~~~~~

617
The HDFS version of LightGBM was tested on CDH-5.14.4 cluster.
618
619
620
621

Linux
^^^^^

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

624
1. Install `CMake`_.
fanliwen's avatar
fanliwen committed
625
626
627
628
629

2. Run the following commands:

   .. code::

630
631
632
633
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
fanliwen's avatar
fanliwen committed
634
     cmake -DUSE_HDFS=ON ..
635
636
637
638
639
640
     # 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
641
642
     make -j4

643
644
645
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

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

Windows
^^^^^^^

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

653
654
VS Build Tools
**************
655

656
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).
657
658
659
660
661
662
663

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

3. Run the following commands:

   .. code::

664
     git clone --recursive https://github.com/microsoft/LightGBM
665
666
667
     cd LightGBM
     mkdir build
     cd build
668
     cmake -A x64 -DUSE_SWIG=ON ..
669
670
     cmake --build . --target ALL_BUILD --config Release

671
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/Release`` folder.
672
673
674
675
676
677
678
679
680
681
682
683

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::

684
     git clone --recursive https://github.com/microsoft/LightGBM
685
686
687
688
689
690
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..
     mingw32-make.exe -j4

691
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/`` folder.
692
693
694

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

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

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

700
701
702
Linux
^^^^^

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

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

707
2. Run the following commands:
708

709
710
   .. code::

711
712
713
714
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
715
     cmake -DUSE_SWIG=ON ..
716
     make -j4
717

718
719
720
macOS
^^^^^

721
On macOS a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **Apple Clang** or **gcc**.
722
723
724
725
726
727
728
729
730

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.

731
1. Install `CMake`_ (3.16 or higher):
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746

   .. code::

     brew install cmake

2. Install **OpenMP**:

   .. code::

     brew install libomp

3. Run the following commands:

   .. code::

747
748
749
750
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
     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::

773
774
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
775
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
776
777
     mkdir build
     cd build
778
779
780
781
782
     cmake -DUSE_SWIG=ON -DAPPLE_OUTPUT_DYLIB=ON ..
     make -j4

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

783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
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
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

880

881
882
883
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

884
.. _Python-package: https://github.com/microsoft/LightGBM/tree/master/python-package
885

886
.. _R-package: https://github.com/microsoft/LightGBM/tree/master/R-package
887

888
.. _zip archive: https://github.com/microsoft/LightGBM/archive/master.zip
889

890
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
891
892
893
894
895

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

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

896
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
897
898
899
900
901
902
903

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

904
.. _MS MPI: https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi-release-notes
905
906
907
908
909
910
911

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

912
.. _Boost Binaries: https://sourceforge.net/projects/boost/files/boost-binaries/
913
914

.. _SWIG: http://www.swig.org/download.html
915
916

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