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

4
Here is the guide for the build of LightGBM CLI version.
5
6
7

For the build of Python-package and R-package, please refer to `Python-package`_ and `R-package`_ folders respectively.

8
9
Also you can download artifacts of the latest successful build in master branch: |download artifacts|.

10
11
12
13
14
15
16
17
18
19
**Contents**

-  `Windows <#windows>`__

-  `Linux <#linux>`__

-  `macOS <#macos>`__

-  `Docker <#docker>`__

20
21
- `Threadless Version (not Recommended) <#build-threadless-version-not-recommended>`__

22
23
24
25
26
27
28
29
-  `MPI Version <#build-mpi-version>`__

-  `GPU Version <#build-gpu-version>`__

-  `HDFS Version <#build-hdfs-version>`__

-  `Java Wrapper <#build-java-wrapper>`__

30
31
32
Windows
~~~~~~~

33
34
35
36
On Windows LightGBM can be built using

- **Visual Studio**;

37
- **CMake** and **VS Build Tools**;
38
39

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

41
42
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43
44
45
46

With GUI
********

47
1. Install `Visual Studio`_ (2015 or newer).
48
49
50
51
52

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

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

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

55
   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
56
57
58
59
60
61

The exe file will be in ``LightGBM-master/windows/x64/Release`` folder.

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

62
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).
63
64
65
66
67
68
69
70
71
72
73
74
75
76

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..
     cmake --build . --target ALL_BUILD --config Release

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

77
78
MinGW-w64
^^^^^^^^^
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

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

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" ..
     mingw32-make.exe -j4

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

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

97
98
99
It is recommended to use **Visual Studio** for its better multithreading efficiency in **Windows** for many-core systems (see `FAQ <./FAQ.rst#lightgbm>`__ Question 4 and Question 8).

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

101
102
103
Linux
~~~~~

104
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
105

106
1. Install `CMake`_.
107

108
109
110
111
112
113
114
115
2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake ..
     make -j4
116
117
118

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

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

121
122
macOS
~~~~~
123

124
125
126
127
On macOS LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.

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

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

Nikita Titov's avatar
Nikita Titov committed
131
132
1. Install `CMake`_ (3.12 or higher):

133
   .. code::
Nikita Titov's avatar
Nikita Titov committed
134

135
     brew install cmake
fanliwen's avatar
fanliwen committed
136

137
2. Install **OpenMP**:
fanliwen's avatar
fanliwen committed
138
139
140
141

   .. code::

     brew install libomp
142
143
144
145
146

3. Run the following commands:

   .. code::

fanliwen's avatar
fanliwen committed
147
148
149
150
151
     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake ..
     make -j4

152
153
gcc
^^^
154

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

157
   .. code::
158

159
     brew install cmake
160

161
2. Install **gcc**:
162

163
   .. code::
164

165
166
167
168
169
170
171
172
173
174
175
     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 ..
     make -j4
176

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

179
180
181
182
183
Docker
~~~~~~

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

184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default build version of LightGBM is based on OpenMP.
However, you can build the LightGBM without OpenMP support, but it is **strongly not recommended**.

Windows
^^^^^^^

On Windows version of LightGBM without OpenMP support can be built using

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

The exe file will be in ``LightGBM-master/windows/x64/Release`` folder.

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

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_OPENMP=OFF ..
     cmake --build . --target ALL_BUILD --config Release

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

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

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

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..
     mingw32-make.exe -j4

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

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

On Linux version of LightGBM without OpenMP support 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 -DUSE_OPENMP=OFF ..
     make -j4

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

macOS
^^^^^

On macOS version of LightGBM without OpenMP support 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.12 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 -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::

     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 -DUSE_OPENMP=OFF ..
     make -j4

329
330
331
Build MPI Version
~~~~~~~~~~~~~~~~~

332
333
The default build version of LightGBM is based on socket. LightGBM also supports MPI.
`MPI`_ is a high performance communication approach with `RDMA`_ support.
334
335
336
337
338
339

If you need to run a parallel learning application with high performance communication, you can build the LightGBM with MPI support.

Windows
^^^^^^^

340
341
342
343
On Windows MPI version of LightGBM can be built using

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

344
- **MS MPI**, **CMake** and **VS Build Tools**.
345

346
347
348
With GUI
********

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

351
2. Install `Visual Studio`_ (2015 or newer).
352
353
354
355
356

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

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

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

359
   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
360
361
362
363
364
365

The exe file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.

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

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

368
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).
369
370
371
372
373
374
375
376
377
378
379
380
381
382

3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_MPI=ON ..
     cmake --build . --target ALL_BUILD --config Release

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

383
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
384
385
386
387

Linux
^^^^^

388
On Linux MPI version of LightGBM can be built using **Open MPI**, **CMake** and **gcc** or **Clang**.
389

390
1. Install `Open MPI`_.
391

392
2. Install `CMake`_.
393

394
395
396
397
398
399
400
401
3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake -DUSE_MPI=ON ..
     make -j4
402
403
404

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

405
406
macOS
^^^^^
407

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

410
411
Apple Clang
***********
412

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

415
1. Install `CMake`_ (3.12 or higher):
416

417
   .. code::
418

419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
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::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     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::

     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 -DUSE_MPI=ON ..
     make -j4
472
473
474
475
476
477
478

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

Linux
^^^^^

479
480
On Linux GPU version of LightGBM can be built using **OpenCL**, **Boost**, **CMake** and **gcc** or **Clang**.

481
482
The following dependencies should be installed before compilation:

483
-  **OpenCL** 1.2 headers and libraries, which is usually provided by GPU manufacture.
484
485
486

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

487
-  **libboost** 1.56 or later (1.61 or later is recommended).
488
489
490
491
492

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

493
-  **CMake** 3.2 or later.
494
495
496
497
498
499
500
501

To build LightGBM GPU version, run the following commands:

.. code::

  git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
  mkdir build ; cd build
  cmake -DUSE_GPU=1 ..
502
503
  # 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/ ..
504
505
506
507
508
  make -j4

Windows
^^^^^^^

509
On Windows GPU version of LightGBM can be built using **OpenCL**, **Boost**, **CMake** and **VS Build Tools** or **MinGW**.
510

511
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.
512

513
514
Following procedure is for the **MSVC** (Microsoft Visual C++) build.

515
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).
516
517
518
519
520

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

521
   - For running on AMD, get AMD APP SDK.
522
523
524

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

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

527
528
3. Install `Boost Binary`_.

529
   **Note**: Match your Visual C++ version:
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
   
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

   Visual Studio 2017 -> ``msvc-14.1-64.exe``.

4. Run the following commands:

   .. code::

     Set BOOST_ROOT=C:\local\boost_1_64_0\
     Set BOOST_LIBRARYDIR=C:\local\boost_1_64_0\lib64-msvc-14.0
     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_GPU=1 ..
     cmake --build . --target ALL_BUILD --config Release

548
   **Note**: ``C:\local\boost_1_64_0\`` and ``C:\local\boost_1_64_0\lib64-msvc-14.0`` are locations of your **Boost** binaries. You also can set them to the environment variable to avoid ``Set ...`` commands when build.
549
550
551
552
553
554

Docker
^^^^^^

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

555
556
557
Build HDFS Version
~~~~~~~~~~~~~~~~~~

558
**Note**: Installation process of HDFS version is untested.
559
560
561
562

Linux
^^^^^

563
On Linux HDFS version of LightGBM can be built using **CMake** and **gcc** or **Clang**.
564

565
1. Install `CMake`_.
fanliwen's avatar
fanliwen committed
566
567
568
569
570
571
572
573
574
575

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake -DUSE_HDFS=ON ..
     make -j4

576
577
578
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

579
580
581
582
583
By the following instructions you can generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.

Windows
^^^^^^^

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

586
587
VS Build Tools
**************
588

589
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).
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627

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

3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_SWIG=ON ..
     cmake --build . --target ALL_BUILD --config Release

The jar file will be in ``LightGBM/build`` folder and the dll files will be in ``LightGBM/Release`` folder.

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

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..
     mingw32-make.exe -j4

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

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

628
It is recommended to use **VS Build Tools (Visual Studio)** for its better multithreading efficiency in **Windows** for many-core systems (see `FAQ <./FAQ.rst#lightgbm>`__ Question 4 and Question 8).
629
630
631

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

632
633
634
Linux
^^^^^

635
On Linux Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **gcc** or **Clang**.
636

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

639
2. Run the following commands:
640

641
642
643
644
645
   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake -DUSE_SWIG=ON ..
646
     make -j4
647

648
649
650
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

651
652
653
654
655
656
.. _Python-package: https://github.com/Microsoft/LightGBM/tree/master/python-package

.. _R-package: https://github.com/Microsoft/LightGBM/tree/master/R-package

.. _zip archive: https://github.com/Microsoft/LightGBM/archive/master.zip

657
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
658
659
660
661
662

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

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

663
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
664
665
666
667
668
669
670

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

671
.. _MS MPI: https://www.microsoft.com/en-us/download/details.aspx?id=57467
672
673
674
675
676
677
678
679

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

.. _Boost Binary: https://sourceforge.net/projects/boost/files/boost-binaries/1.64.0/
680
681

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