Skip to main content

LightGBM Python-package

Project description

License Python Versions PyPI Version PyPI Downloads conda Version conda Downloads API Docs

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.

Install from PyPI

pip install lightgbm

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 and Linux 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 on Windows and PoCL on Linux. Many modern Linux distributions provide packages for PoCL, look for pocl-opencl-icd on Debian-based distributions and pocl on RedHat-based distributions.

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

In some rare cases, when you hit OSError: libgomp.so.1: cannot open shared object file: No such file or directory error during importing LightGBM, you need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

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, Xcode_9.4.1 for versions 2.3.2 - 3.3.2 and Xcode_11.7 from version 4.0.0) 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.

Use LightGBM with Dask

To install all dependencies needed to use lightgbm.dask, append [dask].

pip install 'lightgbm[dask]'

Use LightGBM with pandas

To install all dependencies needed to use pandas in LightGBM, append [pandas].

pip install 'lightgbm[pandas]'

Use LightGBM with scikit-learn

To install all dependencies needed to use scikit-learn in LightGBM, append [scikit-learn].

pip install 'lightgbm[scikit-learn]'

Build from Sources

pip install --no-binary lightgbm lightgbm

Also, in some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this).

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.

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

Build Threadless Version
pip install lightgbm --config-settings=cmake.define.USE_OPENMP=OFF

All requirements, except the OpenMP requirement, from Build from Sources section apply for this installation option as well.

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

Build MPI Version
pip install lightgbm --config-settings=cmake.define.USE_MPI=ON

All requirements from Build from Sources section apply for this installation option as well.

For Windows users, compilation with MinGW-w64 is not supported.

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

Build GPU Version
pip install lightgbm --config-settings=cmake.define.USE_GPU=ON

All requirements from Build from Sources section apply for this installation option as well.

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 \
  --config-settings=cmake.define.USE_GPU=ON \
  --config-settings=cmake.define.OpenCL_INCLUDE_DIR="/usr/local/cuda/include/" \
  --config-settings=cmake.define.OpenCL_LIBRARY="/usr/local/cuda/lib64/libOpenCL.so"

All available options that can be passed via cmake.define.{option}.

  • Boost_ROOT

  • Boost_DIR

  • Boost_INCLUDE_DIR

  • BOOST_LIBRARYDIR

  • OpenCL_INCLUDE_DIR

  • OpenCL_LIBRARY

For more details see FindBoost and FindOpenCL.

Build CUDA Version
pip install lightgbm --config-settings=cmake.define.USE_CUDA=ON

All requirements from Build from Sources section apply for this installation option as well.

CUDA library is needed: details for installation can be found in Installation Guide.

To use the CUDA version within Python, pass {"device": "cuda"} respectively in parameters.

Build with MinGW-w64 on Windows
# in sh.exe, git bash, or other Unix-like shell
export CMAKE_GENERATOR='MinGW Makefiles'
pip install lightgbm --config-settings=cmake.define.CMAKE_SH=CMAKE_SH-NOTFOUND

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
# in sh.exe, git bash, or other Unix-like shell
export CMAKE_GENERATOR='Visual Studio 17 2022'
export CMAKE_GENERATOR_PLATFORM='Win32'
pip install --no-binary lightgbm lightgbm

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!

Build with Time Costs Output
pip install lightgbm --config-settings=cmake.define.USE_TIMETAG=ON

Use this option to make LightGBM output time costs for different internal routines, to investigate and benchmark its performance.

Install from conda-forge channel

lightgbm conda packages are available from the conda-forge channel.

conda install -c conda-forge lightgbm

These are precompiled packages that are fast to install. Use them instead of pip install if any of the following are true:

  • you prefer to use conda to manage software environments

  • you want to use GPU-accelerated LightGBM

  • you are using a platform that lightgbm does not provide wheels for (like PowerPC)

For lightgbm>=4.4.0, if you are on a system where CUDA is installed, conda install will automatically select a CUDA-enabled build of lightgbm.

conda install -c conda-forge 'lightgbm>=4.4.0'

Install from GitHub

All requirements from Build from Sources section apply for this installation option as well.

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.

git clone --recursive https://github.com/microsoft/LightGBM.git
# export CXX=g++-14 CC=gcc-14  # macOS users, if you decided to compile with gcc, don't forget to specify compilers
sh ./build-python.sh install

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

Run sh ./build-python.sh install --nomp to disable OpenMP support. All requirements from Build Threadless Version section apply for this installation option as well.

Run sh ./build-python.sh install --mpi to enable MPI support. All requirements from Build MPI Version section apply for this installation option as well.

Run sh ./build-python.sh install --mingw, if you want to use MinGW-w64 on Windows instead of Visual Studio. All requirements from Build with MinGW-w64 on Windows section apply for this installation option as well.

Run sh ./build-python.sh install --gpu to enable GPU support. All requirements from Build GPU Version section apply for this installation option as well. To pass additional options to CMake use the following syntax: sh ./build-python.sh install --gpu --opencl-include-dir="/usr/local/cuda/include/", see Build GPU Version section for the complete list of them.

Run sh ./build-python.sh install --cuda to enable CUDA support. All requirements from Build CUDA Version section apply for this installation option as well.

Run sh ./build-python.sh install --bit32, if you want to use 32-bit version. All requirements from Build 32-bit Version with 32-bit Python section apply for this installation option as well.

Run sh ./build-python.sh install --time-costs, if you want to output time costs for different internal routines. All requirements from Build with Time Costs Output section apply for this installation option as well.

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 sh ./build-python.sh install --precompile.

Build Wheel File

You can use sh ./build-python.sh bdist_wheel to build a wheel file but not install it.

That script requires some dependencies like build, scikit-build-core, and wheel. In environments with restricted or no internet access, install those tools and then pass --no-isolation.

sh ./build-python.sh bdist_wheel --no-isolation

Build With MSBuild

To use MSBuild (Windows-only), first build lib_lightgbm.dll by running the following from the root of the repo.

MSBuild.exe windows/LightGBM.sln /p:Configuration=DLL /p:Platform=x64 /p:PlatformToolset=v143

Then install the Python-package using that library.

sh ./build-python.sh install --precompile

Troubleshooting

Refer to FAQ.

Examples

Refer to the walk through examples in Python guide folder.

Development Guide

To check that a contribution to the package matches its style expectations, run the following from the root of the repo.

bash .ci/lint-python-bash.sh

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lightgbm-4.6.0.tar.gz (1.7 MB view details)

Uploaded Source

Built Distributions

lightgbm-4.6.0-py3-none-win_amd64.whl (1.5 MB view details)

Uploaded Python 3Windows x86-64

lightgbm-4.6.0-py3-none-manylinux_2_28_x86_64.whl (3.6 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

lightgbm-4.6.0-py3-none-manylinux2014_aarch64.whl (3.5 MB view details)

Uploaded Python 3

lightgbm-4.6.0-py3-none-macosx_12_0_arm64.whl (1.6 MB view details)

Uploaded Python 3macOS 12.0+ ARM64

lightgbm-4.6.0-py3-none-macosx_10_15_x86_64.whl (2.0 MB view details)

Uploaded Python 3macOS 10.15+ x86-64

File details

Details for the file lightgbm-4.6.0.tar.gz.

File metadata

  • Download URL: lightgbm-4.6.0.tar.gz
  • Upload date:
  • Size: 1.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for lightgbm-4.6.0.tar.gz
Algorithm Hash digest
SHA256 cb1c59720eb569389c0ba74d14f52351b573af489f230032a1c9f314f8bab7fe
MD5 35c499b5ff697a91cf5ffce0af26e4aa
BLAKE2b-256 680ba2e9f5c5da7ef047cc60cef37f86185088845e8433e54d2e7ed439cce8a3

See more details on using hashes here.

File details

Details for the file lightgbm-4.6.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: lightgbm-4.6.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.5 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for lightgbm-4.6.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 37089ee95664b6550a7189d887dbf098e3eadab03537e411f52c63c121e3ba4b
MD5 47e39a919a777f9a18328fd9209ebb27
BLAKE2b-256 5e23f8b28ca248bb629b9e08f877dd2965d1994e1674a03d67cd10c5246da248

See more details on using hashes here.

File details

Details for the file lightgbm-4.6.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for lightgbm-4.6.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 cb19b5afea55b5b61cbb2131095f50538bd608a00655f23ad5d25ae3e3bf1c8d
MD5 ee4a5d4fbb287672039a9433f329c2e1
BLAKE2b-256 4286dabda8fbcb1b00bcfb0003c3776e8ade1aa7b413dff0a2c08f457dace22f

See more details on using hashes here.

File details

Details for the file lightgbm-4.6.0-py3-none-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for lightgbm-4.6.0-py3-none-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4d68712bbd2b57a0b14390cbf9376c1d5ed773fa2e71e099cac588703b590336
MD5 6cff9cfa262b16f11c337daaa3677d29
BLAKE2b-256 64414fbde2c3d29e25ee7c41d87df2f2e5eda65b431ee154d4d462c31041846c

See more details on using hashes here.

File details

Details for the file lightgbm-4.6.0-py3-none-macosx_12_0_arm64.whl.

File metadata

File hashes

Hashes for lightgbm-4.6.0-py3-none-macosx_12_0_arm64.whl
Algorithm Hash digest
SHA256 2dafd98d4e02b844ceb0b61450a660681076b1ea6c7adb8c566dfd66832aafad
MD5 518d9ddca777fcb4236bbf8ef2c38e9c
BLAKE2b-256 211b550ee378512b78847930f5d74228ca1fdba2a7fbdeaac9aeccc085b0e257

See more details on using hashes here.

File details

Details for the file lightgbm-4.6.0-py3-none-macosx_10_15_x86_64.whl.

File metadata

File hashes

Hashes for lightgbm-4.6.0-py3-none-macosx_10_15_x86_64.whl
Algorithm Hash digest
SHA256 b7a393de8a334d5c8e490df91270f0763f83f959574d504c7ccb9eee4aef70ed
MD5 26de093567ba031c9de10abd9234890a
BLAKE2b-256 f275cffc9962cca296bc5536896b7e65b4a7cdeb8db208e71b9c0133c08f8f7e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page