building:index — numpy 2.5.0.dev0+git20251130.2de293a

Building NumPy from source requires setting up system-level dependencies (compilers, BLAS/LAPACK libraries, etc.) first, and then invoking a build. The build may be done in order to install NumPy for local usage, develop NumPy itself, or build redistributable binary packages. And it may be desired to customize aspects of how the build is done. This guide will cover all these aspects. In addition, it provides background information on how the NumPy build works, and links to up-to-date guides for generic Python build & packaging documentation that is relevant.

System-level dependencies

NumPy uses compiled code for speed, which means you need compilers and some other system-level (i.e, non-Python / non-PyPI) dependencies to build it on your system.

Building NumPy from source

If you want to only install NumPy from source once and not do any development work, then the recommended way to build and install is to use pip. Otherwise, conda is recommended.

Building from source to use NumPy

Building from source for NumPy development

If you want to build from source in order to work on NumPy itself, first clone the NumPy repository

git clone https://github.com/numpy/numpy.git
cd numpy
git submodule update --init

Then you want to do the following:

Create a dedicated development environment (virtual environment or conda environment),
Install all needed dependencies (build, and also test, doc and optional dependencies),
Build NumPy with the spin developer interface.

Step (3) is always the same, steps (1) and (2) are different between conda and virtual environments:

To build NumPy in an activated development environment, run

spin build

This will install NumPy inside the repository (by default in a build-install directory). You can then run tests (spin test), drop into IPython (spin ipython), or take other development steps like build the html documentation or running benchmarks. The spin interface is self-documenting, so please see spin --help and spin <subcommand> --help for detailed guidance.

IDE support & editable installs

While the spin interface is our recommended way of working on NumPy, it has one limitation: because of the custom install location, NumPy installed using spin will not be recognized automatically within an IDE (e.g., for running a script via a "run" button, or setting breakpoints visually). This will work better with an in-place build (or "editable install").

Editable installs are supported. It is important to understand that you may use either an editable install or spin in a given repository clone, but not both. If you use editable installs, you have to use pytest and other development tools directly instead of using spin.

To use an editable install, ensure you start from a clean repository (run git clean -xdf if you've built with spin before) and have all dependencies set up correctly as described higher up on this page. Then do

# Note: the --no-build-isolation is important!
pip install -e . --no-build-isolation

# To run the tests for, e.g., the `numpy.linalg` module:
pytest numpy/linalg

When making changes to NumPy code, including to compiled code, there is no need to manually rebuild or reinstall. NumPy is automatically rebuilt each time NumPy is imported by the Python interpreter; see the meson-python documentation on editable installs for more details on how that works under the hood.

When you run git clean -xdf, which removes the built extension modules, remember to also uninstall NumPy with pip uninstall numpy.

Building from source

System-level dependencies

Building NumPy from source

Building from source to use NumPy

Building from source for NumPy development

Customizing builds

Background information