From 88177691b8acafa5f288b4b850b83f84aa4fa808 Mon Sep 17 00:00:00 2001 From: Joe Nyland Date: Mon, 20 Nov 2017 01:12:16 +0000 Subject: [PATCH] Update README (#2204) I found the installation of the Python XGBoost package to be problematic as the documentation around compiler requirements was unclear, as discussed in #1501. I decided that I would improve the README. --- python-package/README.rst | 100 ++++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 48 deletions(-) diff --git a/python-package/README.rst b/python-package/README.rst index 0d634a086..cee08c39f 100644 --- a/python-package/README.rst +++ b/python-package/README.rst @@ -1,67 +1,71 @@ +====================== XGBoost Python Package ====================== |PyPI version| +Notes +===== + +- Windows users: pip installation may not work on some Windows environments, and it may cause unexpected errors. + + Installation from pip on Windows is therefore currently disabled for further investigation; please `install from Github `_ instead. +- If you want to run XGBoost process in parallel using the fork backend for joblib/multiprocessing, you must build XGBoost without support for OpenMP by ``make no_omp=1``. Otherwise, use the forkserver (in Python 3.4) or spawn backend. See the `sklearn\_parallel.py <../demo/guide-python/sklearn_parallel.py>`__ demo. + +Requirements +============ + +Since this package contains C++ source code, ``pip`` needs a C++ compiler from the system to compile the source code on-the-fly. + +macOS +----- + +On macOS, ``gcc@5`` is required as later versions remove support for OpenMP. `See here `_ for more info. + +Please install ``gcc@5`` from `Homebrew `_:: + + brew install gcc@5 + +Linux +----- + +Please install ``gcc``:: + + sudo apt-get install build-essential # Ubuntu/Debian + sudo yum groupinstall 'Development Tools' # CentOS/RHEL + Installation ------------- +============ -We are on `PyPI `__ now. For -stable version, please install using pip: +From `PyPI `_ +--------------------------------------------------- -- ``pip install xgboost`` -- Since this package contains C++ source code, ``pip`` needs a C++ compiler from the system - to compile the source code on-the-fly. Please follow the following instruction for each - supported platform. -- Note for Mac OS X users: please install ``gcc`` from ``brew`` by - ``brew tap homebrew/versions; brew install gcc --without-multilib`` firstly. -- Note for Linux users: please install ``gcc`` by ``sudo apt-get install build-essential`` firstly - or using the corresponding package manager of the system. -- Note for windows users: this pip installation may not work on some - windows environment, and it may cause unexpected errors. pip - installation on windows is currently disabled for further - investigation, please install from github. +For a stable version, install using ``pip``:: -For up-to-date version, please install from github. + pip install xgboost -- To make the python module, type ``./build.sh`` in the root directory - of project -- Make sure you have - `setuptools `__ -- Install with ``cd python-package; python setup.py install`` from this directory. -- For windows users, please use the Visual Studio project file under - `windows folder <../windows/>`__. See also the `installation - tutorial `__ - from Kaggle Otto Forum. -- Add MinGW to the system PATH in Windows if you are using the latest version of xgboost which requires compilation: +From source +----------- - ```python +For an up-to-date version, `install from Github `_: + +- Run ``./build.sh`` in the root of the repo. +- Make sure you have `setuptools `_ installed: ``pip install setuptools`` +- Install with ``cd python-package; python setup.py install`` from the root of the repo +- For Windows users, please use the Visual Studio project file under the `Windows folder <../windows/>`_. See also the `installation + tutorial `_ from Kaggle Otto Forum. +- Add MinGW to the system PATH in Windows if you are using the latest version of xgboost which requires compilation:: + + python import os os.environ['PATH'] = os.environ['PATH'] + ';C:\\Program Files\\mingw-w64\\x86_64-5.3.0-posix-seh-rt_v4-rev0\\mingw64\\bin' - ``` Examples --------- +======== -- Refer also to the walk through example in `demo - folder `__ -- See also the `example scripts `__ for Kaggle - Higgs Challenge, including `speedtest - script `__ on this dataset. - -Note ----- - -- If you want to build xgboost on Mac OS X with multiprocessing support - where clang in XCode by default doesn't support, please install gcc - 4.9 or higher using `homebrew `__ - ``brew tap homebrew/versions; brew install gcc --without-multilib`` -- If you want to run XGBoost process in parallel using the fork backend - for joblib/multiprocessing, you must build XGBoost without support - for OpenMP by ``make no_omp=1``. Otherwise, use the forkserver (in - Python 3.4) or spawn backend. See the - `sklearn\_parallel.py <../demo/guide-python/sklearn_parallel.py>`__ - demo. +- Refer also to the walk through example in `demo folder `_. +- See also the `example scripts `_ for Kaggle + Higgs Challenge, including `speedtest script `_ on this dataset. .. |PyPI version| image:: https://badge.fury.io/py/xgboost.svg :target: http://badge.fury.io/py/xgboost