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 https://scipy.org/install.html.
Contents
Building NumPy requires the following installed software:
Python__ 3.7.x or newer.
Please note that the Python development headers also need to be installed, e.g., on Debian/Ubuntu one needs to install both python3 and python3-dev. On Windows and macOS this is normally not an issue.
Cython >= 0.29.21
pytest__ (optional) 1.15 or later
This is required for testing NumPy, but not for using it.
Hypothesis__ (optional) 5.3.0 or later
This is required for testing NumPy, but not for using it.
Python__ https://www.python.org/ pytest__ https://docs.pytest.org/en/stable/ Hypothesis__ https://hypothesis.readthedocs.io/en/latest/
Note
If you want to build NumPy in order to work on NumPy itself, use
runtests.py
. For more details, see
https://numpy.org/devdocs/dev/development_environment.html
Note
More extensive information on building NumPy is maintained at https://numpy.org/devdocs/user/building.html#building-from-source
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
See Requirements for Installing Packages for more details.
The number of build jobs can also be specified via the environment variable NPY_NUM_BUILD_JOBS.
NumPy needs a C compiler, and for development versions also needs 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.
For Fortran, gfortran
works, g77
does not. In case g77
is
installed then g77
will be detected and used first. To explicitly select
gfortran
in that case, do:
python setup.py build --fcompiler=gnu95
On Windows, building from source can be difficult (in particular if you need to build SciPy as well, because that requires a Fortran compiler). Currently, the most robust option is to use MSVC (for NumPy only). If you also need SciPy, you can either use MSVC + Intel Fortran or the Intel compiler suite. Intel itself maintains a good application note on this.
If you want to use a free compiler toolchain, our current recommendation is to use Docker or Windows subsystem for Linux (WSL). See https://scipy.github.io/devdocs/dev/contributor/contributor_toc.html#development-environment for more details.
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.
The Intel compilers work with Intel MKL, see the application note linked above.
For an overview of the state of BLAS/LAPACK libraries on Windows, see here.
You will need to install a BLAS/LAPACK library. We recommend using OpenBLAS or Intel MKL. Apple's Accelerate also still works, however it has bugs and we are likely to drop support for it in the near future.
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 instructionslibopenblas-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 ...
If you run into build issues and need help, the NumPy and SciPy mailing list 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.