From 1bd91fe7efff404b1bc8701904950056c97a6925 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 10 Jul 2024 14:56:44 -0700 Subject: [PATCH 1/3] [docs] update and simplify installation docs --- docs/FAQ.rst | 8 +++--- docs/Installation-Guide.rst | 16 ------------ python-package/README.rst | 49 ++++++++++++++++++++----------------- 3 files changed, 31 insertions(+), 42 deletions(-) diff --git a/docs/FAQ.rst b/docs/FAQ.rst index 2e24256a974f..a3d4db62f2a4 100644 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -329,6 +329,8 @@ Also, feel free to post a new issue in our GitHub repository. We always look at 4. I would like to install LightGBM from conda. What channel should I choose? ----------------------------------------------------------------------------- -We strongly recommend installation from the ``conda-forge`` channel and not from the ``default`` one 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 in `this comment `__. +We strongly recommend installation from the ``conda-forge`` channel and not from the ``default`` one due. + +For some specific examples, see `this comment `__. + +In addition, as of ``lightgbm==4.4.0``, the ``conda-forge`` package automatically supports CUDA-based GPU acceleration. diff --git a/docs/Installation-Guide.rst b/docs/Installation-Guide.rst index c59898032b70..9b774da7f958 100644 --- a/docs/Installation-Guide.rst +++ b/docs/Installation-Guide.rst @@ -121,8 +121,6 @@ On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**. cmake -B build -S . cmake --build build -j4 -**Note**: glibc >= 2.28 is required. - **Note**: 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). Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__. @@ -301,8 +299,6 @@ On Linux a version of LightGBM without OpenMP support can be built using **CMake cmake -B build -S . -DUSE_OPENMP=OFF cmake --build build -j4 -**Note**: glibc >= 2.14 is required. - macOS ^^^^^ @@ -425,8 +421,6 @@ On Linux an MPI version of LightGBM can be built using **Open MPI**, **CMake** a cmake -B build -S . -DUSE_MPI=ON cmake --build build -j4 -**Note**: glibc >= 2.14 is required. - **Note**: 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). macOS @@ -530,8 +524,6 @@ To build LightGBM GPU version, run the following commands: # cmake -B build -S . -DUSE_GPU=1 -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/ cmake --build build -**Note**: glibc >= 2.14 is required. - **Note**: 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). Windows @@ -613,8 +605,6 @@ To build LightGBM CUDA version, run the following commands: cmake -B build -S . -DUSE_CUDA=1 cmake --build build -j4 -**Note**: glibc >= 2.14 is required. - **Note**: 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). macOS @@ -659,8 +649,6 @@ On Linux a HDFS version of LightGBM can be built using **CMake** and **gcc**. # .. cmake --build build -j4 -**Note**: glibc >= 2.14 is required. - **Note**: 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). Build Java Wrapper @@ -732,8 +720,6 @@ On Linux a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMa cmake -B build -S . -DUSE_SWIG=ON cmake --build build -j4 -**Note**: glibc >= 2.14 is required. - **Note**: 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). macOS @@ -834,8 +820,6 @@ On Linux a C++ unit tests of LightGBM can be built using **CMake** and **gcc** o cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF cmake --build build --target testlightgbm -j4 -**Note**: glibc >= 2.14 is required. - macOS ^^^^^ diff --git a/python-package/README.rst b/python-package/README.rst index 86d5da32b755..463cc0247a9f 100644 --- a/python-package/README.rst +++ b/python-package/README.rst @@ -70,17 +70,15 @@ Build from Sources pip install --no-binary lightgbm lightgbm -For **Linux** and **macOS** users, installation from sources requires installed `CMake`_. - -For **Linux** users, **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 for ``lib[g|i]omp`` for doing this). +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 and **CMake** version 3.16 or higher is required. +- 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. If you get any errors during installation, you may need to install `CMake`_ (version 3.8 or higher). +For **Windows** users, **Visual Studio** (or `VS Build Tools `_) is needed. Build Threadless Version ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -102,7 +100,7 @@ Build MPI Version All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well. -For **Windows** users, compilation with **MinGW-w64** is not supported and `CMake`_ (version 3.8 or higher) is strongly required. +For **Windows** users, compilation with **MinGW-w64** is not supported. **MPI** libraries are needed: details for installation can be found in `Installation Guide `__. @@ -115,8 +113,6 @@ Build GPU Version All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well. -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 .. code:: sh @@ -149,9 +145,9 @@ Build CUDA Version pip install lightgbm --config-settings=cmake.define.USE_CUDA=ON -All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well, and `CMake`_ (version 3.16 or higher) is strongly required. +All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well. -**CUDA** library (version 10.0 or higher) is needed: details for installation can be found in `Installation Guide `__. +**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. @@ -181,7 +177,7 @@ Build with MinGW-w64 on Windows export CMAKE_GENERATOR='MinGW Makefiles' pip install lightgbm --config-settings=cmake.define.CMAKE_SH=CMAKE_SH-NOTFOUND -`CMake`_ and `MinGW-w64 `_ should be installed first. +`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 `__). @@ -212,27 +208,37 @@ Use this option to make LightGBM output time costs for different internal routin Install from `conda-forge channel `_ ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' -If you use ``conda`` to manage Python dependencies, you can install LightGBM using ``conda install``. +``lightgbm`` conda packages are available from the ``conda-forge`` channel. + +.. code:: sh + + conda install -c conda-forge lightgbm + +The are precompiled packages that are fast to install. +Use them instead of ``pip install`` if any of the following are true: -We strongly recommend installation from the ``conda-forge`` channel and not from the ``default`` one 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 in `this comment `_. +* 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) -**Note**: The `lightgbm conda-forge feedstock `_ is not maintained by LightGBM maintainers. +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``. .. code:: sh - conda install -c conda-forge lightgbm + conda install -c conda-forge 'lightgbm>=4.4.0' Install from GitHub ''''''''''''''''''' All requirements from `Build from Sources section <#build-from-sources>`__ 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, you should install `CMake`_ (version 3.8 or higher). +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. .. code:: sh git clone --recursive https://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) + # 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. @@ -258,10 +264,10 @@ If you get any errors during installation or due to any other reasons, you may w Build Wheel File **************** -You can use ``sh ./build-python.sh install bdist_wheel`` to build a wheel file but not install it. +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 internt access, install those tools and then pass ``--no-isolation``. +In environments with restricted or no internet access, install those tools and then pass ``--no-isolation``. .. code:: sh @@ -285,8 +291,6 @@ Then install the Python package using that library. 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 @@ -301,7 +305,7 @@ To check that a contribution to the package matches its style expectations, run .. code:: sh - sh .ci/lint-python.sh + bash .ci/lint-python.sh .. |License| image:: https://img.shields.io/github/license/microsoft/lightgbm.svg :target: https://github.com/microsoft/LightGBM/blob/master/LICENSE @@ -313,4 +317,3 @@ To check that a contribution to the package matches its style expectations, run :target: https://pepy.tech/project/lightgbm .. |API Docs| image:: https://readthedocs.org/projects/lightgbm/badge/?version=latest :target: https://lightgbm.readthedocs.io/en/latest/Python-API.html -.. _CMake: https://cmake.org/ From 6b2b79a8ff48e767981102488fe6d3561cdf0c4c Mon Sep 17 00:00:00 2001 From: James Lamb Date: Sat, 13 Jul 2024 15:41:41 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Nikita Titov --- docs/FAQ.rst | 2 +- python-package/README.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/FAQ.rst b/docs/FAQ.rst index a3d4db62f2a4..4584863180d4 100644 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -329,7 +329,7 @@ Also, feel free to post a new issue in our GitHub repository. We always look at 4. I would like to install LightGBM from conda. What channel should I choose? ----------------------------------------------------------------------------- -We strongly recommend installation from the ``conda-forge`` channel and not from the ``default`` one due. +We strongly recommend installation from the ``conda-forge`` channel and not from the ``default`` one. For some specific examples, see `this comment `__. diff --git a/python-package/README.rst b/python-package/README.rst index bcaab539fb0a..0412ea45efbe 100644 --- a/python-package/README.rst +++ b/python-package/README.rst @@ -197,7 +197,7 @@ Install from `conda-forge channel `_ conda install -c conda-forge lightgbm -The are precompiled packages that are fast to install. +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 From 8cee2d623cf54823e0c88de37044f64051ca54e2 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Sat, 13 Jul 2024 15:53:27 -0700 Subject: [PATCH 3/3] remove more references to CMake and GLIBC versions --- R-package/README.md | 2 +- python-package/README.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/R-package/README.md b/R-package/README.md index c769d1a7eb9b..cde306a81654 100644 --- a/R-package/README.md +++ b/R-package/README.md @@ -142,7 +142,7 @@ Rscript build_r.R --use-msys2 #### Mac OS Preparation -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](https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang)) 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](https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc)) and set some environment variables to tell R to use `gcc` and `g++`. If you install these from Homebrew, your versions of `g++` and `gcc` are most likely in `/usr/local/bin`, as shown below. +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](https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang)) first. 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 set some environment variables to tell R to use `gcc` and `g++`. If you install these from Homebrew, your versions of `g++` and `gcc` are most likely in `/usr/local/bin`, as shown below. ``` # replace 8 with version of gcc installed on your machine diff --git a/python-package/README.rst b/python-package/README.rst index 0412ea45efbe..3912b6905ce3 100644 --- a/python-package/README.rst +++ b/python-package/README.rst @@ -22,7 +22,7 @@ Compiled library that is included in the wheel file supports both **GPU** and ** 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 LightGBM ``<=3.3.3`` and **glibc** >= 2.28 is required for newer versions. Also, 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). +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: