Skip to content

GitLab

Unverified Commit 830763d9 authored by James Lamb's avatar James Lamb Committed by GitHub
Browse files

[docs] update and simplify installation docs (#6536) 



* [docs] update and simplify installation docs

* Apply suggestions from code review
Co-authored-by: default avatarNikita Titov <nekit94-08@mail.ru>

* remove more references to CMake and GLIBC versions

---------
Co-authored-by: default avatarNikita Titov <nekit94-08@mail.ru>
parent 5cec6903
Show whitespace changes
Inline Side-by-side
Showing with 33 additions and 42 deletions
R-package/README.md
View file @ 830763d9
......@@ -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
......
docs/FAQ.rst
View file @ 830763d9
......@@ -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.
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.
docs/Installation-Guide.rst
View file @ 830763d9
......@@ -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
......@@ -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
......@@ -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
^^^^^
......
python-package/README.rst
View file @ 830763d9
......@@ -22,7 +22,7 @@ Compiled library that is included in the wheel file supports both **GPU** and **
For **Windows** users, `VC runtime <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_ 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:
......@@ -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 <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
~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -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>`__.
......@@ -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
......@@ -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.
......@@ -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>`__).
......@@ -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
These 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 <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.
......@@ -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
......@@ -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
......@@ -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
......@@ -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/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment