Skip to content

clean up installation doc organization #10698

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

Merged
merged 6 commits into from
Jun 28, 2018
Merged

clean up installation doc organization #10698

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dd7fcad
clean up installation doc organization
amueller Feb 25, 2018
279bdb2
update os x instructions to python3, suggest editable install by defa…
amueller May 26, 2018
cb0a313
Merge branch 'master' into install_doc_reorg
amueller May 26, 2018
a591d13
Merge branch 'master' into install_doc_reorg
amueller Jun 28, 2018
174c4ef
address comments.
amueller Jun 28, 2018
cd8dffb
add pandas dependency for tests.
amueller Jun 28, 2018
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
243 changes: 69 additions & 174 deletions doc/developers/advanced_installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,58 +7,98 @@ Advanced installation instructions

There are different ways to get scikit-learn installed:

* :ref:`Install an official release <install_official_release>`. This
is the best approach for most users. It will provide a stable version
and pre-build packages are available for most platforms.

* Install the version of scikit-learn provided by your
:ref:`operating system or Python distribution <install_by_distribution>`.
This is the quickest option for those who have operating systems that
distribute scikit-learn.

* :ref:`Install an official release <install_official_release>`. This
is the best approach for users who want a stable version number
and aren't concerned about running a slightly older version of
scikit-learn.
This is a quick option for those who have operating systems
that distribute scikit-learn. It might not provide the latest release
version.

* :ref:`Install the latest development version
* :ref:`Building the package from source
<install_bleeding_edge>`. This is best for users who want the
latest-and-greatest features and aren't afraid of running
brand-new code.
brand-new code. This document describes how to build from source.

.. note::

If you wish to contribute to the project, you need to
:ref:`install the latest development version<install_bleeding_edge>`.

.. _install_bleeding_edge:

.. _install_official_release:

Installing an official release
==============================
Building from source
=====================

Scikit-learn requires:

- Python (>= 2.7 or >= 3.4),
- NumPy (>= 1.8.2),
- SciPy (>= 0.13.3).

Building Scikit-learn also requires
Copy link
Member Author

Choose a reason for hiding this comment

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

since this is the building section this header might be superfluous?


Mac OSX
-------
- Cython >=0.23

Scikit-learn and its dependencies are all available as wheel packages for OSX::
Running tests requires

pip install -U numpy scipy scikit-learn
- pytest

Copy link
Member

Choose a reason for hiding this comment

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

Some tests require pandas

Copy link
Member Author

Choose a reason for hiding this comment

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

not to self: sync with current travis setup. Also maybe point to the travis setup file here?

Some tests also require `pandas <https://pandas.pydata.org>`_.

Linux
-----
.. _git_repo:

Retrieving the latest code
--------------------------

We use `Git <https://git-scm.com/>`_ for version control and
`GitHub <https://github.com/>`_ for hosting our main repository.

At this time scikit-learn does not provide official binary packages for Linux
so you have to build from source if you want the latest version.
If you don't need the newest version, consider using your package manager to
install scikit-learn. It is usually the easiest way, but might not provide the
newest version.
You can check out the latest sources with the command::

git clone git://github.com/scikit-learn/scikit-learn.git

If you want to build a stable version, you can ``git checkout <VERSION>``
to get the code for that particular version, or download an zip archive of
the version from github.

If you have all the build requirements installed (see below for details), you
can build and install the package in the following way.

If you run the development version, it is cumbersome to reinstall the
package each time you update the sources. Therefore it's recommended that you
install in editable, which allows you to edit the code in-place. This
builds the extension in place and creates a link to the development directory
(see `the pip docs <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_)::

pip install --editable .

.. note::

This is fundamentally similar to using the command ``python setup.py develop``
(see `the setuptool docs <http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_).
It is however preferred to use pip.

.. note::

If you decide to do an editable install you have to rerun::

pip install --editable .

every time the source code of a compiled extension is
changed (for instance when switching branches or pulling changes from upstream).

On Unix-like systems, you can simply type ``make`` in the top-level folder to
build in-place and launch all the tests. Have a look at the ``Makefile`` for
additional utilities.

Installing build dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=============================

Linux
-----

Installing from source requires you to have installed the scikit-learn runtime
dependencies, Python development headers and a working C/C++ compiler.
Expand Down Expand Up @@ -118,145 +158,9 @@ On Red Hat and clones (e.g. CentOS), install the dependencies using::
sudo yum -y install gcc gcc-c++ numpy python-devel scipy


Building scikit-learn with pip
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is usually the fastest way to install or upgrade to the latest stable
release::

pip install --user --install-option="--prefix=" -U scikit-learn

The ``--user`` flag asks pip to install scikit-learn in the ``$HOME/.local``
folder therefore not requiring root permission. This flag should make pip
ignore any old version of scikit-learn previously installed on the system while
benefiting from system packages for numpy and scipy. Those dependencies can
be long and complex to build correctly from source.

The ``--install-option="--prefix="`` flag is only required if Python has a
``distutils.cfg`` configuration with a predefined ``prefix=`` entry.


From source package
~~~~~~~~~~~~~~~~~~~

download the source package from
`pypi <https://pypi.python.org/pypi/scikit-learn>`__, unpack the sources and
cd into the source directory.

This packages uses distutils, which is the default way of installing
python modules. The install command is::

python setup.py install

or alternatively (also from within the scikit-learn source folder)::

pip install .

.. warning::

Packages installed with the ``python setup.py install`` command cannot
be uninstalled nor upgraded by ``pip`` later. To properly uninstall
scikit-learn in that case it is necessary to delete the ``sklearn`` folder
from your Python ``site-packages`` directory.


Windows
-------

First, you need to install `numpy <http://www.numpy.org/>`_ and `scipy
<http://www.scipy.org/>`_ from their own official installers.

Wheel packages (.whl files) for scikit-learn from `pypi
<https://pypi.python.org/pypi/scikit-learn/>`_ can be installed with the `pip
<https://pip.readthedocs.io/en/stable/installing/>`_ utility.
Open a console and type the following to install or upgrade scikit-learn to the
latest stable release::

pip install -U scikit-learn

If there are no binary packages matching your python, version you might
to try to install scikit-learn and its dependencies from `christoph gohlke
unofficial windows installers
<https://www.lfd.uci.edu/~gohlke/pythonlibs/#scikit-learn>`_
or from a :ref:`python distribution <install_by_distribution>` instead.


.. _install_by_distribution:

Third party distributions of scikit-learn
=========================================

Some third-party distributions are now providing versions of
scikit-learn integrated with their package-management systems.

These can make installation and upgrading much easier for users since
the integration includes the ability to automatically install
dependencies (numpy, scipy) that scikit-learn requires.

The following is an incomplete list of python and os distributions
that provide their own version of scikit-learn.


MacPorts for Mac OSX
--------------------

The MacPorts package is named ``py<XY>-scikits-learn``,
where ``XY`` denotes the Python version.
It can be installed by typing the following
command::

sudo port install py26-scikit-learn

or::

sudo port install py27-scikit-learn


Arch Linux
----------

Arch Linux's package is provided through the `official repositories
<https://www.archlinux.org/packages/?q=scikit-learn>`_ as
``python-scikit-learn`` for Python 3 and ``python2-scikit-learn`` for Python 2.
It can be installed by typing the following command:

.. code-block:: none

# pacman -S python-scikit-learn

or:

.. code-block:: none

# pacman -S python2-scikit-learn

depending on the version of Python you use.


NetBSD
------

scikit-learn is available via `pkgsrc-wip <http://pkgsrc-wip.sourceforge.net/>`_:

http://pkgsrc.se/wip/py-scikit_learn

Fedora
------

The Fedora package is called ``python-scikit-learn`` for the Python 2 version
and ``python3-scikit-learn`` for the Python 3 version. Both versions can
be installed using ``yum``::

$ sudo yum install python-scikit-learn

or::

$ sudo yum install python3-scikit-learn


Building on windows
-------------------

To build scikit-learn on Windows you need a working C/C++ compiler in
addition to numpy, scipy and setuptools.

Expand Down Expand Up @@ -358,16 +262,6 @@ build step::
where ``my_compiler`` should be one of ``mingw32`` or ``msvc``.


.. _install_bleeding_edge:

Bleeding Edge
=============

See section :ref:`git_repo` on how to get the development version. Then follow
the previous instructions to build from source depending on your platform.
You will also require Cython >=0.23 in order to build the development version.


.. _testing:

Testing
Expand All @@ -377,8 +271,9 @@ Testing scikit-learn once installed
-----------------------------------

Testing requires having the `pytest
<https://docs.pytest.org>`_ library. After
installation, the package can be tested by executing *from outside* the
<https://docs.pytest.org>`_ library. Some tests also require having
`pandas <https://pandas.pydata.org/>` installed.
After installation, the package can be tested by executing *from outside* the
source directory::

$ pytest sklearn
Expand All @@ -388,7 +283,7 @@ eventually should finish with a message similar to::

=========== 8304 passed, 26 skipped, 4659 warnings in 557.76 seconds ===========

Otherwise, please consider posting an issue into the `bug tracker
Otherwise, please consider posting an issue into the `GitHub issue tracker
<https://github.com/scikit-learn/scikit-learn/issues>`_ or to the
:ref:`mailing_lists` including the traceback of the individual failures
and errors. Please include your operating system, your version of NumPy, SciPy
Expand Down
56 changes: 8 additions & 48 deletions doc/developers/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,14 @@ See :ref:`new_contributors` to get started.

|


In case you experience issues using this package, do not hesitate to submit a
ticket to the
`GitHub issue tracker <https://github.com/scikit-learn/scikit-learn/issues>`_. You are
also welcome to post feature requests or pull requests.


=======
Ways to contribute
==================

Expand Down Expand Up @@ -144,54 +152,6 @@ feedback:
for more details.


.. _git_repo:

Retrieving the latest code
==========================

We use `Git <https://git-scm.com/>`_ for version control and
`GitHub <https://github.com/>`_ for hosting our main repository.

You can check out the latest sources with the command::

git clone git://github.com/scikit-learn/scikit-learn.git

or if you have write privileges::

git clone git@github.com:scikit-learn/scikit-learn.git

If you run the development version, it is cumbersome to reinstall the
package each time you update the sources. It is thus preferred that
you add the scikit-learn directory to your ``PYTHONPATH`` and build the
extension in place::

python setup.py build_ext --inplace


Another option is to install the package in editable mode if you change your
code a lot and do not want to have to reinstall every time. This basically
builds the extension in place and creates a link to the development directory
(see `the pip docs <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_)::

pip install --editable .

.. note::

This is fundamentally similar to using the command ``python setup.py develop`` (see `the setuptool docs <http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_). It is however preferred to use pip.

.. note::

If you decide to do an editable install you have to rerun::

python setup.py build_ext --inplace

every time the source code of a compiled extension is
changed (for instance when switching branches or pulling changes from upstream).

On Unix-like systems, you can simply type ``make`` in the top-level folder to
build in-place and launch all the tests. Have a look at the ``Makefile`` for
additional utilities.


Contributing code
=================
Expand Down
Loading