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 https://scipy.org/install.html.

Contents

Prerequisites
Basic installation
Choosing compilers
- Windows
Building with optimized BLAS support
Build issues

Prerequisites

Building NumPy requires the following installed software:

Python__ 3.11.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 >= 3.0.6
pytest__ (optional)

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 spin. 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/building/#building-numpy-from-source

Basic installation

If this is a clone of the NumPy git repository, then first initialize the git submodules:

git submodule update --init

To install NumPy, run:

pip install .

This will compile NumPy on all available CPUs and install it into the active environment.

To run the build from the source folder for development purposes, use the spin development CLI:

spin build    # installs in-tree under `build-install/`
spin ipython  # drop into an interpreter where `import numpy` picks up the local build

Alternatively, use an editable install with:

pip install -e . --no-build-isolation

See Requirements for Installing Packages for more details.

Choosing compilers

NumPy needs C and C++ compilers, 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 more options including selecting compilers, setting custom compiler flags and controlling parallelism, see https://scipy.github.io/devdocs/building/compilers_and_options.html

Windows

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.

Building with optimized BLAS support

Configuring which BLAS/LAPACK is used if you have multiple libraries installed is done via a --config-settings CLI flag - if not given, the default choice is OpenBLAS. If your installed library is in a non-standard location, selecting that location is done via a pkg-config .pc file. See https://scipy.github.io/devdocs/building/blas_lapack.html for more details.

Windows

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.

macOS

On macOS >= 13.3, you can use Apple's Accelerate library. On older macOS versions, Accelerate has bugs and we recommend using OpenBLAS or (on x86-64) Intel MKL.

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