Package: lightgbm
InstallationPreparation32-bit Python is not supported. Please install 64-bit version. If you have a strong need to install with 32-bit Python, refer toBuild 32-bit Version with 32-bit Python section.setuptoolsis needed.Install fromPyPIpipinstalllightgbmCompiled library that is included in the wheel file supports bothGPUandCPUversions out of the box. This feature is experimental and available only forWindowsandLinuxcurrently. To useGPUversion 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 installAMD APP SDKonWindowsandPoCLonLinux. Many modern Linux distributions provide packages for PoCL, look forpocl-opencl-icdon Debian-based distributions andpoclon RedHat-based distributions.ForWindowsusers,VC runtimeis needed ifVisual Studio(2015 or newer) is not installed.ForLinuxusers,glibc>= 2.14 is required for LightGBM<=3.3.3andglibc>= 2.28 is required for newer versions. Also, in some rare cases, when you hitOSError: libgomp.so.1: cannot open shared object file: No such file or directoryerror during importing LightGBM, you need to install OpenMP runtime library separately (use your package manager and search forlib[g|i]ompfor doing this).FormacOS(we provide wheels for 3 newest macOS versions) users:Starting from version 2.2.1, the library file in distribution wheels is built by theApple 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 thegcccompiler anymore. Instead of that you need to install theOpenMPlibrary, which is required for running LightGBM on the system with theApple Clangcompiler. You can install theOpenMPlibrary by the following command:brew install libomp.For version smaller than 2.2.1 and not smaller than 2.1.2,gcc-8withOpenMPsupport must be installed first. Refer toInstallation Guidefor installation ofgcc-8withOpenMPsupport.For version smaller than 2.1.2,gcc-7withOpenMPis required.Use LightGBM with DaskWarningDask-package is only tested on Linux.To install all dependencies needed to uselightgbm.dask, append[dask].pipinstall'lightgbm[dask]'Use LightGBM with pandasTo install all dependencies needed to usepandasin LightGBM, append[pandas].pipinstall'lightgbm[pandas]'Use LightGBM with scikit-learnTo install all dependencies needed to usescikit-learnin LightGBM, append[scikit-learn].pipinstall'lightgbm[scikit-learn]'Build from Sourcespipinstall--no-binarylightgbmlightgbmForLinuxandmacOSusers, installation from sources requires installedCMake.ForLinuxusers,glibc>= 2.28 is required. Also, in some rare cases you may need to install OpenMP runtime library separately (use your package manager and search forlib[g|i]ompfor doing this).FormacOSusers, you can perform installation either withApple Clangorgcc.In case you preferApple Clang, you should installOpenMP(details for installation can be found inInstallation Guide) first andCMakeversion 3.16 or higher is required.In case you prefergcc, you need to install it (details for installation can be found inInstallation Guide) and specify compilers by runningexportCXX=g++-7CC=gcc-7(replace “7” with version ofgccinstalled on your machine) first.ForWindowsusers,Visual Studio(orVS Build Tools) is needed. If you get any errors during installation, you may need to installCMake(version 3.8 or higher).Build Threadless Versionpipinstalllightgbm--config-settings=cmake.define.USE_OPENMP=OFFAll requirements, except theOpenMPrequirement, fromBuild from Sources sectionapply for this installation option as well.It isstrongly not recommendedto use this version of LightGBM!Build MPI Versionpipinstalllightgbm--config-settings=cmake.define.USE_MPI=ONAll requirements fromBuild from Sources sectionapply for this installation option as well.ForWindowsusers, compilation withMinGW-w64is not supported andCMake(version 3.8 or higher) is strongly required.MPIlibraries are needed: details for installation can be found inInstallation Guide.Build GPU Versionpipinstalllightgbm--config-settings=cmake.define.USE_GPU=ONAll requirements fromBuild from Sources sectionapply for this installation option as well.ForWindowsusers,CMake(version 3.8 or higher) is strongly required.BoostandOpenCLare needed: details for installation can be found inInstallation Guide. Almost always you also need to passOpenCL_INCLUDE_DIR,OpenCL_LIBRARYoptions forLinuxandBOOST_ROOT,BOOST_LIBRARYDIRoptions forWindowstoCMakeviapipoptions, likepipinstalllightgbm\--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 viacmake.define.{option}.Boost_ROOTBoost_DIRBoost_INCLUDE_DIRBOOST_LIBRARYDIROpenCL_INCLUDE_DIROpenCL_LIBRARYFor more details seeFindBoostandFindOpenCL.Build CUDA Versionpipinstalllightgbm--config-settings=cmake.define.USE_CUDA=ONAll requirements fromBuild from Sources sectionapply for this installation option as well, andCMake(version 3.16 or higher) is strongly required.CUDAlibrary (version 10.0 or higher) is needed: details for installation can be found inInstallation Guide.To use the CUDA version within Python, pass{"device": "cuda"}respectively in parameters.Build HDFS Versionpipinstalllightgbm--config-settings=cmake.define.USE_HDFS=ONAll requirements fromBuild from Sources sectionapply for this installation option as well.HDFSlibrary is needed: details for installation can be found inInstallation Guide.Note that the installation process of HDFS version was tested only onLinux.Build with MinGW-w64 on Windows# in sh.exe, git bash, or other Unix-like shellexportCMAKE_GENERATOR='MinGW Makefiles'pipinstalllightgbm--config-settings=cmake.define.CMAKE_SH=CMAKE_SH-NOTFOUNDCMakeandMinGW-w64should be installed first.It is recommended to useVisual Studiofor its better multithreading efficiency inWindowsfor many-core systems
(seeQuestion 4andQuestion 8).Build 32-bit Version with 32-bit Python# in sh.exe, git bash, or other Unix-like shellexportCMAKE_GENERATOR='Visual Studio 17 2022'exportCMAKE_GENERATOR_PLATFORM='Win32'pipinstall--no-binarylightgbmlightgbmBy default, installation in environment with 32-bit Python is prohibited. However, you can remove this prohibition on your own risk by passingbit32option.It isstrongly not recommendedto use this version of LightGBM!Build with Time Costs Outputpipinstalllightgbm--config-settings=cmake.define.USE_TIMETAG=ONUse this option to make LightGBM output time costs for different internal routines, to investigate and benchmark its performance.Install fromconda-forge channelIf you usecondato manage Python dependencies, you can install LightGBM usingconda install.We strongly recommend installation from theconda-forgechannel and not from thedefaultone due to many reasons. The main ones are less time delay for new releases, greater number of supported architectures and better handling of dependency conflicts, especially workaround for OpenMP is crucial for LightGBM. More details can be found inthis comment.Note: Thelightgbm conda-forge feedstockis not maintained by LightGBM maintainers.condainstall-cconda-forgelightgbmInstall from GitHubAll requirements fromBuild from Sources sectionapply for this installation option as well.ForWindowsusers, if you get any errors during installation and there is the warningWARNING:LightGBM:Compilation with MSBuild from existing solution file failed.in the log, you should installCMake(version 3.8 or higher).gitclone--recursivehttps://github.com/microsoft/LightGBM.git# 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)sh./build-python.shinstallNote:sudo(or administrator rights inWindows) may be needed to perform the command.Runsh./build-python.shinstall--nompto disableOpenMPsupport. All requirements fromBuild Threadless Version sectionapply for this installation option as well.Runsh./build-python.shinstall--mpito enableMPIsupport. All requirements fromBuild MPI Version sectionapply for this installation option as well.Runsh./build-python.shinstall--mingw, if you want to useMinGW-w64onWindowsinstead ofVisual Studio. All requirements fromBuild with MinGW-w64 on Windows sectionapply for this installation option as well.Runsh./build-python.shinstall--gputo enable GPU support. All requirements fromBuild GPU Version sectionapply for this installation option as well. To pass additional options toCMakeuse the following syntax:sh./build-python.shinstall--gpu--opencl-include-dir="/usr/local/cuda/include/", seeBuild GPU Version sectionfor the complete list of them.Runsh./build-python.shinstall--cudato enable CUDA support. All requirements fromBuild CUDA Version sectionapply for this installation option as well.Runsh./build-python.shinstall--hdfsto enable HDFS support. All requirements fromBuild HDFS Version sectionapply for this installation option as well.Runsh./build-python.shinstall--bit32, if you want to use 32-bit version. All requirements fromBuild 32-bit Version with 32-bit Python sectionapply for this installation option as well.Runsh./build-python.shinstall--time-costs, if you want to output time costs for different internal routines. All requirements fromBuild with Time Costs Output sectionapply 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 (seeInstallation Guide) and then just runsh./build-python.shinstall--precompile.Build Wheel FileYou can usesh./build-python.shinstall bdist_wheelto build a wheel file but not install it.That script requires some dependencies likebuild,scikit-build-core, andwheel.
In environments with restricted or no internt access, install those tools and then pass--no-isolation.sh./build-python.shbdist_wheel--no-isolationBuild With MSBuildTo useMSBuild(Windows-only), first buildlib_lightgbm.dllby running the following from the root of the repo.MSBuild.exewindows/LightGBM.sln/p:Configuration=DLL/p:Platform=x64/p:PlatformToolset=v143Then install the Python package using that library.sh./build-python.shinstall--precompileTroubleshootingIn case you are facing any errors during the installation process, you can examine$HOME/LightGBM_compilation.logfile, 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 toFAQ.ExamplesRefer to the walk through examples inPython guide folder.Development GuideThe code style of Python-package followsPEP 8.The package’s documentation strings (docstrings) are written in thenumpydoc style.To check that a contribution to the package matches its style expectations, run the following from the root of the repo.sh.ci/lint-python.sh