Building from source

Building locally on your machine gives you complete control over build options. If you are a MacOS or Linux user familiar with using the command line, you can continue with building NumPy locally by following the instructions below.

Note

If you want to build NumPy for development purposes, please refer to Setting up and using your development environment for additional information.

Prerequisites

Building NumPy requires the following software installed:

  1. Python 3.9.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.

  2. Compilers

    Much of NumPy is written in C and C++. You will need a C compiler that complies with the C99 standard, and a C++ compiler that complies with the C++17 standard.

    While a FORTRAN 77 compiler is not necessary for building NumPy, it is needed to run the numpy.f2py tests. These tests are skipped if the compiler is not auto-detected.

    Note that NumPy is developed mainly using GNU compilers and tested on MSVC and Clang compilers. Compilers from other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Portland, Lahey, HP, IBM are only supported in the form of community feedback, and may not work out of the box. GCC 6.5 (and later) compilers are recommended. On ARM64 (aarch64) GCC 8.x (and later) are recommended.

  3. Linear Algebra libraries

    NumPy does not require any external linear algebra libraries to be installed. However, if these are available, NumPy’s setup script can detect them and use them for building. A number of different LAPACK library setups can be used, including optimized LAPACK libraries such as OpenBLAS or MKL. The choice and location of these libraries as well as include paths and other such build options can be specified in a .pc file, as documented in scipy:building-blas-and-lapack.

  4. Cython

    For building NumPy, you’ll need a recent version of Cython.

  5. The NumPy source code

    Clone the repository following the instructions in Contributing to NumPy.

Note

Starting on version 1.26, NumPy will adopt Meson as its build system (see Status of numpy.distutils and migration advice and scipy:building/understanding_meson for more details.)

Basic installation

To build and install NumPy from a local copy of the source code, run:

pip install .

This will install all build dependencies and use Meson to compile and install the NumPy C-extensions and Python modules. If you need more control of build options and commands, see the following sections.

To perform an in-place build that can be run from the source folder run:

pip install -r build_requirements.txt
pip install -e . --no-build-isolation

Note: for build instructions to do development work on NumPy itself, see Setting up and using your development environment.

Advanced building with Meson

Meson supports the standard environment variables CC, CXX and FC to select specific C, C++ and/or Fortran compilers. These environment variables are documented in the reference tables in the Meson docs.

Note that environment variables only get applied from a clean build, because they affect the configure stage (i.e., meson setup). An incremental rebuild does not react to changes in environment variables - you have to run git clean -xdf and do a full rebuild, or run meson setup --reconfigure.

For more options including selecting compilers, setting custom compiler flags and controlling parallelism, see scipy:building/compilers_and_options (from the SciPy documentation) and the Meson FAQ.

Testing

Make sure to test your builds. To ensure everything stays in shape, see if all tests pass.

The test suite requires additional dependencies, which can easily be installed with:

python -m pip install -r test_requirements.txt

Run the full test suite with:

cd ..  # avoid picking up the source tree
pytest --pyargs numpy

For detailed info on testing, see Testing builds.

Accelerated BLAS/LAPACK libraries

NumPy searches for optimized linear algebra libraries such as BLAS and LAPACK. There are specific orders for searching these libraries, as described below and in the meson_options.txt file.

Cross compilation

For cross compilation instructions, see scipy:building/cross_compilation and the Meson documentation.