lightgbm 3.1.1

LightGBM Python Package

Installation

Preparation

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.

setuptools is needed.

Install from PyPI Using pip

pip install lightgbm

You may need to install wheel via pip install wheel first.

For Windows users, VC runtime is needed if Visual Studio (2015 or newer) is not installed.

For Linux users, glibc >= 2.14 is required.

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

• 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.
• 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 for installation of gcc-8 with OpenMP support.
• For version smaller than 2.1.2, gcc-7 with OpenMP is required.

Build from Sources

pip install --no-binary :all: lightgbm

For Linux and macOS users, installation from sources requires installed CMake.

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

• In case you prefer Apple Clang, you should install OpenMP (details for installation can be found in Installation Guide) first and CMake version 3.16 or higher is required.
• In case you prefer gcc, you need to install it (details for installation can be found in Installation Guide) and specify compilers by running export CXX=g++-7 CC=gcc-7 (replace “7” with version of gcc installed on your machine) first.

For Windows users, Visual Studio (or VS Build Tools) is needed. If you get any errors during installation, you may need to install CMake (version 3.8 or higher).

Build Threadless Version

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

All remarks, except the OpenMP requirement for macOS users, from Build from Sources section are actual in this case.

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

Build MPI Version

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

All remarks from Build from Sources section 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.

MPI libraries are needed: details for installation can be found in Installation Guide.

Build GPU Version

pip install lightgbm --install-option=--gpu

All remarks from Build from Sources section are actual in this case.

For Windows users, CMake (version 3.8 or higher) is strongly required.

Boost and OpenCL are needed: details for installation can be found in Installation Guide. 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

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

For more details see FindBoost and FindOpenCL.

Build HDFS Version

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

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

Build with MinGW-w64 on Windows

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

CMake and MinGW-w64 should be installed first.

It is recommended to use Visual Studio for its better multithreading efficiency in Windows for many-core systems (see Question 4 and Question 8).

Build 32-bit Version with 32-bit Python

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!

Install from GitHub

All remarks from Build from Sources section are actual in this case.

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

git clone --recursive https://github.com/microsoft/LightGBM.git
cd LightGBM/python-package
# 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)
python setup.py install

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

Run python setup.py install --nomp to disable OpenMP support. All remarks from Build Threadless Version section are actual in this case.

Run python setup.py install --mpi to enable MPI support. All remarks from Build MPI Version section are actual in this case.

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 are actual in this case.

Run python setup.py install --gpu to enable GPU support. All remarks from Build GPU Version section 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 for the complete list of them.

Run python setup.py install --hdfs to enable HDFS support. All remarks from Build HDFS Version section are actual in this case.

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 are actual in this case.

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) and then just run python setup.py install --precompile.

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.

Troubleshooting

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.

Refer to FAQ.

Examples

Refer to the walk through examples in Python guide folder.

Development Guide

The code style of Python-package follows PEP 8. 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.

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