forked from dmlc/xgboost
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
I found the installation of the Python XGBoost package to be problematic as the documentation around compiler requirements was unclear, as discussed in dmlc#1501. I decided that I would improve the README.
- Loading branch information
Showing
1 changed file
with
58 additions
and
54 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 <https://xgboost.readthedocs.io/en/latest/build.html>`_ 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 <https://github.com/dmlc/xgboost/issues/1501#issuecomment-292209578>`_ for more info. | ||
|
||
Please install ``gcc@5`` from `Homebrew <https://brew.sh/>`_:: | ||
|
||
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 <https://pypi.python.org/pypi/xgboost>`__ now. For | ||
stable version, please install using pip: | ||
|
||
- ``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 up-to-date version, please install from github. | ||
|
||
- To make the python module, type ``./build.sh`` in the root directory | ||
of project | ||
- Make sure you have | ||
`setuptools <https://pypi.python.org/pypi/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 <https://www.kaggle.com/c/otto-group-product-classification-challenge/forums/t/13043/run-xgboost-from-windows-and-python>`__ | ||
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 | ||
============ | ||
|
||
From `PyPI <https://pypi.python.org/pypi/xgboost>`_ | ||
--------------------------------------------------- | ||
|
||
For a stable version, install using ``pip``:: | ||
|
||
pip install xgboost | ||
|
||
From source | ||
----------- | ||
|
||
For an up-to-date version, `install from Github <https://xgboost.readthedocs.io/en/latest/build.html>`_: | ||
|
||
- Run ``./build.sh`` in the root of the repo. | ||
- Make sure you have `setuptools <https://pypi.python.org/pypi/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 <https://www.kaggle.com/c/otto-group-product-classification-challenge/forums/t/13043/run-xgboost-from-windows-and-python>`_ 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 <https://github.com/dmlc/xgboost/tree/master/demo/guide-python>`__ | ||
- See also the `example scripts <https://github.com/dmlc/xgboost/tree/master/demo/kaggle-higgs>`__ for Kaggle | ||
Higgs Challenge, including `speedtest | ||
script <https://github.com/dmlc/xgboost/tree/master/demo/kaggle-higgs/speedtest.py>`__ 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 <http://brew.sh/>`__ | ||
``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 <https://github.com/dmlc/xgboost/tree/master/demo/guide-python>`_. | ||
- See also the `example scripts <https://github.com/dmlc/xgboost/tree/master/demo/kaggle-higgs>`_ for Kaggle | ||
Higgs Challenge, including `speedtest script <https://github.com/dmlc/xgboost/tree/master/demo/kaggle-higgs/speedtest.py>`_ on this dataset. | ||
|
||
.. |PyPI version| image:: https://badge.fury.io/py/xgboost.svg | ||
:target: http://badge.fury.io/py/xgboost |