Building and installing NumPy

+++++++++++++++++++++++++++++

**IMPORTANT**: the below notes are about building NumPy, which for most users

is *not* the recommended way to install NumPy.  Instead, use either a complete

scientific Python distribution (recommended) or a binary installer - see

http://scipy.org/install.html.

.. Contents::

Prerequisites

=============

Building NumPy requires the following software installed:

1) For Python 2, Python__ 2.7.x or newer.

   For Python 3, Python__ 3.4.x or newer.

   On Debian and derivative (Ubuntu): python python-dev

   On Windows: the official python installer on Python__ is enough

   Make sure that the Python package distutils is installed before

   continuing. For example, in Debian GNU/Linux, distutils is included

   in the python-dev package.

   Python must also be compiled with the zlib module enabled.

2) Cython >= 0.19 (for development versions of numpy, not for released

                   versions)

3) nose__ (optional) 1.0 or later

   This is required for testing numpy, but not for using it.

Python__ http://www.python.org

nose__ http://nose.readthedocs.io

.. note:: 

   If you want to build NumPy in order to work on NumPy itself, use

   ``runtests.py``.  For more details, see

   http://docs.scipy.org/doc/numpy-dev/dev/development_environment.html

.. note::

   More extensive information on building NumPy (and Scipy) is maintained at

   http://scipy.org/scipylib/building/index.html

Basic Installation

==================

To install numpy run::

    python setup.py build -j 4 install --prefix $HOME/.local

This will compile numpy on 4 CPUs and install it into the specified prefix.

To perform an inplace build that can be run from the source folder run::

    python setup.py build_ext --inplace -j 4

The number of build jobs can also be specified via the environment variable

NPY_NUM_BUILD_JOBS.

Choosing compilers

==================

NumPy needs a C compiler, and for development versions also Cython.  A Fortran

compiler isn't needed to build NumPy itself; the ``numpy.f2py`` tests will be

skipped when running the test suite if no Fortran compiler is available.  For

building Scipy a Fortran compiler is needed though, so we include some details

on Fortran compilers in the rest of this section.

On OS X and Linux, all common compilers will work.  Note that for Fortran,

``gfortran`` is strongly preferred over ``g77``, but if you happen to have both

installed then ``g77`` will be detected and used first.  To explicitly select

``gfortran`` in that case, do::

    python setup.py build --fcompiler=gnu95

Windows

-------

On Windows, building from source can be difficult.  Currently the most robust

option is to use the Intel compilers, or alternatively MSVC (the same version

as used to build Python itself) with Intel ifort.  Intel itself maintains a

good `application note <https://software.intel.com/en-us/articles/numpyscipy-with-intel-mkl>`_

on this.

If you want to use a free compiler toolchain, the recommended compiler is MingwPy__.

The older MinGW32 compiler set used to produce older .exe installers for NumPy

itself is still available at https://github.com/numpy/numpy-vendor, but not

recommended for use anymore.

MingwPy__ http://mingwpy.github.io

Building with optimized BLAS support

====================================

Configuring which BLAS/LAPACK is used if you have multiple libraries installed,

or you have only one installed but in a non-standard location, is done via a

``site.cfg`` file.  See the ``site.cfg.example`` shipped with NumPy for more

details.

Windows

-------

The Intel compilers work with Intel MKL, see the application note linked above. 

MingwPy__ works with OpenBLAS.

For an overview of the state of BLAS/LAPACK libraries on Windows, see 

`here <http://mingwpy.github.io/blas_lapack.html>`_.

OS X

----

OS X ships the Accelerate framework, which NumPy can build against without any

manual configuration.  Other BLAS/LAPACK implementations (OpenBLAS, Intel MKL,

ATLAS) will also work.

Ubuntu/Debian

-------------

For best performance a development package providing BLAS and CBLAS should be

installed.  Some of the options available are:

- ``libblas-dev``: reference BLAS (not very optimized)

- ``libatlas-base-dev``: generic tuned ATLAS, it is recommended to tune it to

  the available hardware, see /usr/share/doc/libatlas3-base/README.Debian for

  instructions

- ``libopenblas-base``: fast and runtime detected so no tuning required but a

  very recent version is needed (>=0.2.15 is recommended).  Older versions of

  OpenBLAS suffered from correctness issues on some CPUs.

The package linked to when numpy is loaded can be chosen after installation via

the alternatives mechanism::

    update-alternatives --config libblas.so.3

    update-alternatives --config liblapack.so.3

Or by preloading a specific BLAS library with::

    LD_PRELOAD=/usr/lib/atlas-base/atlas/libblas.so.3 python ...

Build issues

============

If you run into build issues and need help, the NumPy

`mailing list <http://scipy.org/scipylib/mailing-lists.html>`_ is the best

place to ask.  If the issue is clearly a bug in NumPy, please file an issue (or

even better, a pull request) at https://github.com/numpy/numpy.