| 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. |