README.rst 11.2 KB
Newer Older
1
LightGBM Python-package
Guolin Ke's avatar
Guolin Ke committed
2
3
=======================

Nikita Titov's avatar
Nikita Titov committed
4
|License| |Python Versions| |PyPI Version| |Downloads| |API Docs|
Guolin Ke's avatar
Guolin Ke committed
5

Guolin Ke's avatar
Guolin Ke committed
6
7
8
Installation
------------

Guolin Ke's avatar
Guolin Ke committed
9
10
11
Preparation
'''''''''''

12
32-bit Python is not supported. Please install 64-bit version. If you have a strong need to install with 32-bit Python, refer to `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__.
Guolin Ke's avatar
Guolin Ke committed
13

14
`setuptools <https://pypi.org/project/setuptools>`_ is needed.
Guolin Ke's avatar
Guolin Ke committed
15

16
Install from `PyPI <https://pypi.org/project/lightgbm>`_ Using ``pip``
17
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
18

19
20
21
22
23
24
25
.. code:: sh

    pip install lightgbm
 

You may need to install `wheel <https://pythonwheels.com>`_ via ``pip install wheel`` first.

26
27
Compiled library that is included in the wheel file supports both **GPU** and **CPU** versions out of the box. This feature is experimental and available only for **Windows** currently. To use **GPU** version you only need to install OpenCL Runtime libraries. For NVIDIA and AMD GPU they are included in the ordinary drivers for your graphics card, so no action is required. If you would like your AMD or Intel CPU to act like a GPU (for testing and debugging) you can install `AMD APP SDK <https://github.com/microsoft/LightGBM/releases/download/v2.0.12/AMD-APP-SDKInstaller-v3.0.130.135-GA-windows-F-x64.exe>`_.

28
For **Windows** users, `VC runtime <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_ is needed if **Visual Studio** (2015 or newer) is not installed.
Guolin Ke's avatar
Guolin Ke committed
29

30
For **Linux** users, **glibc** >= 2.14 is required.
31

32
For **macOS** (we provide wheels for 3 newest macOS versions) users:
33

34
- Starting from version 2.2.1, the library file in distribution wheels is built by the **Apple Clang** (Xcode_8.3.3 for versions 2.2.1 - 2.3.1, and Xcode_9.4.1 from version 2.3.2) compiler. This means that you don't need to install the **gcc** compiler anymore. Instead of that you need to install the **OpenMP** library, which is required for running LightGBM on the system with the **Apple Clang** compiler. You can install the **OpenMP** library by the following command: ``brew install libomp``.
35

36
- For version smaller than 2.2.1 and not smaller than 2.1.2, **gcc-8** with **OpenMP** support must be installed first. Refer to `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc>`__ for installation of **gcc-8** with **OpenMP** support.
37
38

- For version smaller than 2.1.2, **gcc-7** with **OpenMP** is required.
39

Guolin Ke's avatar
Guolin Ke committed
40

41
Build from Sources
42
******************
Guolin Ke's avatar
Guolin Ke committed
43

44
.. code:: sh
Guolin Ke's avatar
Guolin Ke committed
45

46
    pip install --no-binary :all: lightgbm
Guolin Ke's avatar
Guolin Ke committed
47

48
For **Linux** and **macOS** users, installation from sources requires installed `CMake`_.
Guolin Ke's avatar
Guolin Ke committed
49

50
51
For **macOS** users, you can perform installation either with **Apple Clang** or **gcc**.

52
- In case you prefer **Apple Clang**, you should install **OpenMP** (details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang>`__) first and **CMake** version 3.16 or higher is required.
53

54
- In case you prefer **gcc**, you need to install it (details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc>`__) and specify compilers by running ``export CXX=g++-7 CC=gcc-7`` (replace "7" with version of **gcc** installed on your machine) first.
Guolin Ke's avatar
Guolin Ke committed
55

56
For **Windows** users, **Visual Studio** (or `VS Build Tools <https://visualstudio.microsoft.com/downloads/>`_) is needed. If you get any errors during installation, you may need to install `CMake`_ (version 3.8 or higher).
Guolin Ke's avatar
Guolin Ke committed
57

58
59
60
61
62
63
64
Build Threadless Version
~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: sh

    pip install lightgbm --install-option=--nomp

Nikita Titov's avatar
Nikita Titov committed
65
All remarks, except the **OpenMP** requirement for **macOS** users, from `Build from Sources section <#build-from-sources>`__ are actual in this case.
66
67
68

It is **strongly not recommended** to use this version of LightGBM!

69
70
71
72
73
74
75
Build MPI Version
~~~~~~~~~~~~~~~~~

.. code:: sh

    pip install lightgbm --install-option=--mpi

76
77
78
All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case.

For **Windows** users, compilation with **MinGW-w64** is not supported and `CMake`_ (version 3.8 or higher) is strongly required.
79

80
**MPI** libraries are needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-mpi-version>`__.
81

82
Build GPU Version
83
~~~~~~~~~~~~~~~~~
Guolin Ke's avatar
Guolin Ke committed
84

85
.. code:: sh
86

87
    pip install lightgbm --install-option=--gpu
88

89
All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case.
90

91
For **Windows** users, `CMake`_ (version 3.8 or higher) is strongly required.
92

93
**Boost** and **OpenCL** are needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version>`__. Almost always you also need to pass ``OpenCL_INCLUDE_DIR``, ``OpenCL_LIBRARY`` options for **Linux** and ``BOOST_ROOT``, ``BOOST_LIBRARYDIR`` options for **Windows** to **CMake** via ``pip`` options, like
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

.. code:: sh

    pip install lightgbm --install-option=--gpu --install-option="--opencl-include-dir=/usr/local/cuda/include/" --install-option="--opencl-library=/usr/local/cuda/lib64/libOpenCL.so"

All available options:

- boost-root

- boost-dir

- boost-include-dir

- boost-librarydir

- opencl-include-dir

- opencl-library

113
For more details see `FindBoost <https://cmake.org/cmake/help/latest/module/FindBoost.html>`__ and `FindOpenCL <https://cmake.org/cmake/help/latest/module/FindOpenCL.html>`__.
114

115
116
117
118
119
120
121
Build HDFS Version
~~~~~~~~~~~~~~~~~~

.. code:: sh

    pip install lightgbm --install-option=--hdfs

122
Note that the installation process of HDFS version was tested only on **Linux**.
123

124
125
126
127
128
129
130
Build with MinGW-w64 on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: sh

    pip install lightgbm --install-option=--mingw

131
132
`CMake`_ and `MinGW-w64 <https://mingw-w64.org/>`_ should be installed first.

133
134
It is recommended to use **Visual Studio** for its better multithreading efficiency in **Windows** for many-core systems
(see `Question 4 <https://github.com/microsoft/LightGBM/blob/master/docs/FAQ.rst#4-i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__ and `Question 8 <https://github.com/microsoft/LightGBM/blob/master/docs/FAQ.rst#8-cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).
Guolin Ke's avatar
Guolin Ke committed
135

136
137
138
139
140
141
142
143
144
145
146
Build 32-bit Version with 32-bit Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: sh

    pip install lightgbm --install-option=--bit32

By default, installation in environment with 32-bit Python is prohibited. However, you can remove this prohibition on your own risk by passing ``bit32`` option.

It is **strongly not recommended** to use this version of LightGBM!

Guolin Ke's avatar
Guolin Ke committed
147
148
Install from GitHub
'''''''''''''''''''
Guolin Ke's avatar
Guolin Ke committed
149

150
All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case.
Guolin Ke's avatar
Guolin Ke committed
151

152
For **Windows** users, if you get any errors during installation and there is the warning ``WARNING:LightGBM:Compilation with MSBuild from existing solution file failed.`` in the log, you should install `CMake`_ (version 3.8 or higher).
Guolin Ke's avatar
Guolin Ke committed
153

Guolin Ke's avatar
Guolin Ke committed
154
155
.. code:: sh

156
    git clone --recursive https://github.com/microsoft/LightGBM.git
Guolin Ke's avatar
Guolin Ke committed
157
    cd LightGBM/python-package
158
    # export CXX=g++-7 CC=gcc-7  # macOS users, if you decided to compile with gcc, don't forget to specify compilers (replace "7" with version of gcc installed on your machine)
Guolin Ke's avatar
Guolin Ke committed
159
160
    python setup.py install

161
Note: ``sudo`` (or administrator rights in **Windows**) may be needed to perform the command.
162

163
164
Run ``python setup.py install --nomp`` to disable **OpenMP** support. All remarks from `Build Threadless Version section <#build-threadless-version>`__ are actual in this case.

165
Run ``python setup.py install --mpi`` to enable **MPI** support. All remarks from `Build MPI Version section <#build-mpi-version>`__ are actual in this case.
Guolin Ke's avatar
Guolin Ke committed
166

167
Run ``python setup.py install --mingw``, if you want to use **MinGW-w64** on **Windows** instead of **Visual Studio**. All remarks from `Build with MinGW-w64 on Windows section <#build-with-mingw-w64-on-windows>`__ are actual in this case.
168

169
Run ``python setup.py install --gpu`` to enable GPU support. All remarks from `Build GPU Version section <#build-gpu-version>`__ are actual in this case. To pass additional options to **CMake** use the following syntax: ``python setup.py install --gpu --opencl-include-dir=/usr/local/cuda/include/``, see `Build GPU Version section <#build-gpu-version>`__ for the complete list of them.
170

171
Run ``python setup.py install --hdfs`` to enable HDFS support. All remarks from `Build HDFS Version section <#build-hdfs-version>`__ are actual in this case.
Guolin Ke's avatar
Guolin Ke committed
172

173
174
Run ``python setup.py install --bit32``, if you want to use 32-bit version. All remarks from `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__ are actual in this case.

175
If you get any errors during installation or due to any other reasons, you may want to build dynamic library from sources by any method you prefer (see `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst>`__) and then just run ``python setup.py install --precompile``.
wxchan's avatar
wxchan committed
176

177
178
179
180
181
182

Build Wheel File
****************

You can use ``python setup.py bdist_wheel`` instead of ``python setup.py install`` to build wheel file and use it for installation later. This might be useful for systems with restricted or completely without network access.

wxchan's avatar
wxchan committed
183
Troubleshooting
Guolin Ke's avatar
Guolin Ke committed
184
---------------
wxchan's avatar
wxchan committed
185

186
187
In case you are facing any errors during the installation process, you can examine ``$HOME/LightGBM_compilation.log`` file, in which all operations are logged, to get more details about occurred problem. Also, please attach this file to the issue on GitHub to help faster indicate the cause of the error.

188
Refer to `FAQ <https://github.com/microsoft/LightGBM/tree/master/docs/FAQ.rst>`_.
wxchan's avatar
wxchan committed
189

190
191
192
Examples
--------

193
Refer to the walk through examples in `Python guide folder <https://github.com/microsoft/LightGBM/tree/master/examples/python-guide>`_.
194

195
196
Development Guide
-----------------
wxchan's avatar
wxchan committed
197

198
The code style of Python-package follows `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_. If you would like to make a contribution and not familiar with PEP 8, please check the PEP 8 style guide first. Otherwise, the check won't pass. Only E501 (line too long) and W503 (line break occurred before a binary operator) can be ignored.
Guolin Ke's avatar
Guolin Ke committed
199

200
201
Documentation strings (docstrings) are written in the NumPy style.

202
.. |License| image:: https://img.shields.io/github/license/microsoft/lightgbm.svg
203
   :target: https://github.com/microsoft/LightGBM/blob/master/LICENSE
204
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/lightgbm.svg?logo=python&logoColor=white
205
   :target: https://pypi.org/project/lightgbm
206
.. |PyPI Version| image:: https://img.shields.io/pypi/v/lightgbm.svg?logo=pypi&logoColor=white
207
   :target: https://pypi.org/project/lightgbm
208
209
.. |Downloads| image:: https://pepy.tech/badge/lightgbm
   :target: https://pepy.tech/project/lightgbm
Nikita Titov's avatar
Nikita Titov committed
210
211
.. |API Docs| image:: https://readthedocs.org/projects/lightgbm/badge/?version=latest
   :target: https://lightgbm.readthedocs.io/en/latest/Python-API.html
212
.. _CMake: https://cmake.org/