diff --git a/doc/developers/advanced_installation.rst b/doc/developers/advanced_installation.rst index 9029f5991af..c21e1b6bf13 100644 --- a/doc/developers/advanced_installation.rst +++ b/doc/developers/advanced_installation.rst @@ -52,31 +52,31 @@ Linux ----- At this time scikit-learn does not provide official binary packages for Linux -so you have to build from source if you want the lastest version. +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 +install scikit-learn. It is usually the easiest way, but might not provide the newest version. -installing build dependencies +Installing build dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -installing from source requires you to have installed the scikit-learn runtime -dependencies, python development headers and a working C/C++ compiler. -under debian-based operating systems, which include ubuntu, if you have -python 2 you can install all these requirements by issuing:: +Installing from source requires you to have installed the scikit-learn runtime +dependencies, Python development headers and a working C/C++ compiler. +Under Debian-based operating systems, which include Ubuntu, if you have +Python 2 you can install all these requirements by issuing:: sudo apt-get install build-essential python-dev python-setuptools \ python-numpy python-scipy \ libatlas-dev libatlas3gf-base -if you have python 3:: +If you have Python 3:: sudo apt-get install build-essential python3-dev python3-setuptools \ python3-numpy python3-scipy \ libatlas-dev libatlas3gf-base -on recent debian and ubuntu (e.g. ubuntu 13.04 or later) make sure that atlas -is used to provide the implementation of the blas and lapack linear algebra +On recent Debian and Ubuntu (e.g. Ubuntu 13.04 or later) make sure that ATLAS +is used to provide the implementation of the BLAS and LAPACK linear algebra routines:: sudo update-alternatives --set libblas.so.3 \ @@ -86,24 +86,24 @@ routines:: .. note:: - in order to build the documentation and run the example code contains in + In order to build the documentation and run the example code contains in this documentation you will need matplotlib:: sudo apt-get install python-matplotlib .. note:: - the above installs the atlas implementation of blas - (the basic linear algebra subprograms library). - ubuntu 11.10 and later, and recent (testing) versions of debian, - offer an alternative implementation called openblas. + The above installs the ATLAS implementation of BLAS + (the Basic Linear Algebra Subprograms library). + Ubuntu 11.10 and later, and recent (testing) versions of Debian, + offer an alternative implementation called OpenBLAS. - using openblas can give speedups in some scikit-learn modules, - but can freeze joblib/multiprocessing prior to openblas version 0.2.8-4, + Using OpenBLAS can give speedups in some scikit-learn modules, + but can freeze joblib/multiprocessing prior to OpenBLAS version 0.2.8-4, so using it is not recommended unless you know what you're doing. - if you do want to use openblas, then replacing atlas only requires a couple - of commands. atlas has to be removed, otherwise numpy may not work:: + If you do want to use OpenBLAS, then replacing ATLAS only requires a couple + of commands. ATLAS has to be removed, otherwise NumPy may not work:: sudo apt-get remove libatlas3gf-base libatlas-dev sudo apt-get install libopenblas-dev @@ -113,30 +113,30 @@ routines:: sudo update-alternatives --set liblapack.so.3 \ /usr/lib/lapack/liblapack.so.3 -on red hat and clones (e.g. centos), install the dependencies using:: +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 +Building scikit-learn with pip ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -this is usually the fastest way to install or upgrade to the latest stable +This is usually the fastest way to install or upgrade to the latest stable release:: - pip install --user --install-option="--prefix=" -u scikit-learn + 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 +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 +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 +The ``--install-option="--prefix="`` flag is only required if Python has a ``distutils.cfg`` configuration with a predefined ``prefix=`` entry. -from source package +From source package ~~~~~~~~~~~~~~~~~~~ download the source package from @@ -144,7 +144,7 @@ download the source package from cd into the source directory. This packages uses distutils, which is the default way of installing -python modules. the install command is:: +python modules. The install command is:: python setup.py install @@ -154,27 +154,27 @@ or alternatively (also from within the scikit-learn source folder):: .. warning:: - packages installed with the ``python setup.py install`` command cannot - be uninstalled nor upgraded by ``pip`` later. to properly uninstall + 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. + from your Python ``site-packages`` directory. -windows +Windows ------- -first, you need to install `numpy `_ and `scipy +First, you need to install `numpy `_ and `scipy `_ from their own official installers. -wheel packages (.whl files) for scikit-learn from `pypi +Wheel packages (.whl files) for scikit-learn from `pypi `_ can be installed with the `pip `_ utility. -open a console and type the following to install or upgrade scikit-learn to the +Open a console and type the following to install or upgrade scikit-learn to the latest stable release:: - pip install -u scikit-learn + pip install -U scikit-learn -if there are no binary packages matching your python, version you might +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 `_ @@ -186,23 +186,23 @@ or from a :ref:`python distribution ` instead. Third party distributions of scikit-learn ========================================= -some third-party distributions are now providing versions of +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 +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 +The following is an incomplete list of python and os distributions that provide their own version of scikit-learn. -macports for mac osx +MacPorts for Mac OSX -------------------- -the macports package is named ``py-scikits-learn``, -where ``xy`` denotes the python version. -it can be installed by typing the following +The MacPorts package is named ``py-scikits-learn``, +where ``XY`` denotes the Python version. +It can be installed by typing the following command:: sudo port install py26-scikit-learn @@ -212,39 +212,39 @@ or:: sudo port install py27-scikit-learn -arch linux +Arch Linux ---------- -arch linux's package is provided through the `official repositories +Arch Linux's package is provided through the `official repositories `_ as -``python-scikit-learn`` for python 3 and ``python2-scikit-learn`` for python 2. -it can be installed by typing the following command: +``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 + # pacman -S python-scikit-learn or: .. code-block:: none - # pacman -s python2-scikit-learn + # pacman -S python2-scikit-learn -depending on the version of python you use. +depending on the version of Python you use. -netbsd +NetBSD ------ scikit-learn is available via `pkgsrc-wip `_: http://pkgsrc.se/wip/py-scikit_learn -fedora +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 +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 @@ -254,103 +254,103 @@ or:: $ sudo yum install python3-scikit-learn -building on windows +Building on windows ------------------- -to build scikit-learn on windows you need a working C/C++ compiler in +To build scikit-learn on Windows you need a working C/C++ compiler in addition to numpy, scipy and setuptools. -picking the right compiler depends on the version of python (2 or 3) -and the architecture of the python interpreter, 32-bit or 64-bit. -you can check the python version by running the following in ``cmd`` or +Picking the right compiler depends on the version of Python (2 or 3) +and the architecture of the Python interpreter, 32-bit or 64-bit. +You can check the Python version by running the following in ``cmd`` or ``powershell`` console:: python --version and the architecture with:: - python -c "import struct; print(struct.calcsize('p') * 8)" + python -c "import struct; print(struct.calcsize('P') * 8)" -the above commands assume that you have the python installation folder in your -path environment variable. +The above commands assume that you have the Python installation folder in your +PATH environment variable. -32-bit python +32-bit Python ------------- -for 32-bit python it is possible use the standalone installers for +For 32-bit python it is possible use the standalone installers for `microsoft visual c++ express 2008 `_ -for python 2 or microsoft visual c++ express 2010 for python 3. +for Python 2 or Microsoft Visual C++ Express 2010 for Python 3. -once installed you should be able to build scikit-learn without any +Once installed you should be able to build scikit-learn without any particular configuration by running the following command in the scikit-learn folder:: python setup.py install -64-bit python +64-bit Python ------------- -for the 64-bit architecture, you either need the full visual studio or -the free windows sdks that can be downloaded from the links below. +For the 64-bit architecture, you either need the full Visual Studio or +the free Windows SDKs that can be downloaded from the links below. -the windows sdks include the msvc compilers both for 32 and 64-bit -architectures. they come as a ``grmsdkx_en_dvd.iso`` file that can be mounted +The Windows SDKs include the MSVC compilers both for 32 and 64-bit +architectures. They come as a ``GRMSDKX_EN_DVD.iso`` file that can be mounted as a new drive with a ``setup.exe`` installer in it. -- for python 2 you need sdk **v7.0**: `ms windows sdk for windows 7 and .net - framework 3.5 sp1 +- For Python 2 you need SDK **v7.0**: `MS Windows SDK for Windows 7 and .NET + Framework 3.5 SP1 `_ -- for python 3 you need sdk **v7.1**: `ms windows sdk for windows 7 and .net - framework 4 +- For Python 3 you need SDK **v7.1**: `MS Windows SDK for Windows 7 and .NET + Framework 4 `_ -both sdks can be installed in parallel on the same host. to use the windows -sdks, you need to setup the environment of a ``cmd`` console launched with the -following flags (at least for sdk v7.0):: +Both SDKs can be installed in parallel on the same host. To use the Windows +SDKs, you need to setup the environment of a ``cmd`` console launched with the +following flags (at least for SDK v7.0):: - cmd /e:on /v:on /k + cmd /E:ON /V:ON /K -then configure the build environment with:: +Then configure the build environment with:: - set distutils_use_sdk=1 - set mssdk=1 - "c:\program files\microsoft sdks\windows\v7.0\setup\windowssdkver.exe" -q -version:v7.0 - "c:\program files\microsoft sdks\windows\v7.0\bin\setenv.cmd" /x64 /release + SET DISTUTILS_USE_SDK=1 + SET MSSdk=1 + "C:\Program Files\Microsoft SDKs\Windows\v7.0\Setup\WindowsSdkVer.exe" -q -version:v7.0 + "C:\Program Files\Microsoft SDKs\Windows\v7.0\Bin\SetEnv.cmd" /x64 /release -finally you can build scikit-learn in the same ``cmd`` console:: +Finally you can build scikit-learn in the same ``cmd`` console:: python setup.py install -replace ``v7.0`` by the ``v7.1`` in the above commands to do the same for -python 3 instead of python 2. +Replace ``v7.0`` by the ``v7.1`` in the above commands to do the same for +Python 3 instead of Python 2. -replace ``/x64`` by ``/x86`` to build for 32-bit python instead of 64-bit -python. +Replace ``/x64`` by ``/x86`` to build for 32-bit Python instead of 64-bit +Python. -building binary packages and installers +Building binary packages and installers --------------------------------------- -the ``.whl`` package and ``.exe`` installers can be built with:: +The ``.whl`` package and ``.exe`` installers can be built with:: pip install wheel python setup.py bdist_wheel bdist_wininst -b doc/logos/scikit-learn-logo.bmp -the resulting packages are generated in the ``dist/`` folder. +The resulting packages are generated in the ``dist/`` folder. -using an alternative compiler +Using an alternative compiler ----------------------------- -it is possible to use `mingw `_ (a port of gcc to windows -os) as an alternative to msvc for 32-bit python. not that extensions built with -mingw32 can be redistributed as reusable packages as they depend on gcc runtime +It is possible to use `MinGW `_ (a port of GCC to Windows +OS) as an alternative to MSVC for 32-bit Python. Not that extensions built with +mingw32 can be redistributed as reusable packages as they depend on GCC runtime libraries typically not installed on end-users environment. -to force the use of a particular compiler, pass the ``--compiler`` flag to the +To force the use of a particular compiler, pass the ``--compiler`` flag to the build step:: python setup.py build --compiler=my_compiler install @@ -360,62 +360,62 @@ where ``my_compiler`` should be one of ``mingw32`` or ``msvc``. .. _install_bleeding_edge: -bleeding edge +Bleeding Edge ============= -see section :ref:`git_repo` on how to get the development version. then follow +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 +Testing ======= -testing scikit-learn once installed +Testing scikit-learn once installed ----------------------------------- -testing requires having the `nose -`_ library. after +Testing requires having the `nose +`_ library. After installation, the package can be tested by executing *from outside* the source directory:: $ nosetests -v sklearn -under windows, it is recommended to use the following command (adjust the path +Under Windows, it is recommended to use the following command (adjust the path to the ``python.exe`` program) as using the ``nosetests.exe`` program can badly interact with tests that use ``multiprocessing``:: - c:\python34\python.exe -c "import nose; nose.main()" -v sklearn + C:\Python34\python.exe -c "import nose; nose.main()" -v sklearn -this should give you a lot of output (and some warnings) but +This should give you a lot of output (and some warnings) but eventually should finish with a message similar to:: - ran 3246 tests in 260.618s - ok (skip=20) + Ran 3246 tests in 260.618s + OK (SKIP=20) -otherwise, please consider posting an issue into the `bug tracker +Otherwise, please consider posting an issue into the `bug tracker `_ or to the :ref:`mailing_lists` including the traceback of the individual failures -and errors. please include your operation system, your version of numpy, scipy +and errors. Please include your operating system, your version of NumPy, SciPy and scikit-learn, and how you installed scikit-learn. -testing scikit-learn from within the source folder +Testing scikit-learn from within the source folder -------------------------------------------------- -scikit-learn can also be tested without having the package -installed. for this you must compile the sources inplace from the +Scikit-learn can also be tested without having the package +installed. For this you must compile the sources inplace from the source directory:: python setup.py build_ext --inplace -test can now be run using nosetests:: +Test can now be run using nosetests:: nosetests -v sklearn/ -this is automated by the commands:: +This is automated by the commands:: make in @@ -424,7 +424,7 @@ and:: make test -you can also install a symlink named ``site-packages/scikit-learn.egg-link`` +You can also install a symlink named ``site-packages/scikit-learn.egg-link`` to the development folder of scikit-learn with:: pip install --editable .