Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] update and simplify installation docs #6536

Merged
merged 4 commits into from
Jul 14, 2024
Merged

[docs] update and simplify installation docs #6536

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1bd91fe
[docs] update and simplify installation docs
jameslamb Jul 10, 2024
52d40f3
Merge branch 'master' into docs/install-docs
StrikerRUS Jul 13, 2024
6b2b79a
Apply suggestions from code review
jameslamb Jul 13, 2024
8cee2d6
remove more references to CMake and GLIBC versions
jameslamb Jul 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/FAQ.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/microsoft/LightGBM/issues/4948#issuecomment-1013766397>`__.
We strongly recommend installation from the ``conda-forge`` channel and not from the ``default`` one due.
jameslamb marked this conversation as resolved.
Show resolved Hide resolved

For some specific examples, see `this comment <https://github.com/microsoft/LightGBM/issues/4948#issuecomment-1013766397>`__.

In addition, as of ``lightgbm==4.4.0``, the ``conda-forge`` package automatically supports CUDA-based GPU acceleration.
14 changes: 0 additions & 14 deletions docs/Installation-Guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down Expand Up @@ -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
^^^^^

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -697,8 +687,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
Expand Down Expand Up @@ -799,8 +787,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
^^^^^

Expand Down
49 changes: 26 additions & 23 deletions python-package/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this as well?
For **Linux** users, **glibc** >= 2.14 is required for LightGBM ``<=3.3.3`` and **glibc** >= 2.28 is required for newer versions.

LightGBM/python-package/README.rst

Line 25 in 52d40f3

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I think that makes sense.

At first I'd intentionally left this one in, because it is true that on systems where you have older versions of GLIBC, pip install lightgbm will return an sdist (that'll have to be compiled) instead of a wheel.

But looking through it again, I do see that the other sections that explicitly talk about sdists (anything about passing --no-binary lightgbm) are nested underneath this "Install from PyPI" heading. And these GLIBC requirements don't affect your ability to build from an sdist.

I've removed this in 8cee2d6.

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 <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 **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 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 <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).
For **Windows** users, **Visual Studio** (or `VS Build Tools <https://visualstudio.microsoft.com/downloads/>`_) is needed.

Build Threadless Version
~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -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 <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-mpi-version>`__.

Expand All @@ -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 <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

.. code:: sh
Expand Down Expand Up @@ -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 <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-cuda-version>`__.
**CUDA** library is needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-cuda-version>`__.

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

Expand All @@ -164,7 +160,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 <https://www.mingw-w64.org/>`_ should be installed first.
`MinGW-w64 <https://www.mingw-w64.org/>`_ 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 <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>`__).
Expand Down Expand Up @@ -195,27 +191,37 @@ Use this option to make LightGBM output time costs for different internal routin
Install from `conda-forge channel <https://anaconda.org/conda-forge/lightgbm>`_
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

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.
jameslamb marked this conversation as resolved.
Show resolved Hide resolved
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 <https://github.com/microsoft/LightGBM/issues/4948#issuecomment-1013766397>`_.
* 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 <https://github.com/conda-forge/lightgbm-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.
Expand All @@ -239,10 +245,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

Expand All @@ -266,8 +272,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 <https://github.com/microsoft/LightGBM/tree/master/docs/FAQ.rst>`_.

Examples
Expand All @@ -282,7 +286,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
Expand All @@ -294,4 +298,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/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove CMake version from here as well?

LightGBM/R-package/README.md

Line 145 in 2bc3ab8

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, missed this one! Removed in 8cee2d6

Loading