Building from source#

Note

If you are only trying to install NumPy, we recommend using binaries - seeInstallation for details on that.

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

System-level dependencies#

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

Note

If you are using Conda, you can skip the steps in this section - with theexception of installing compilers for Windows or the Apple Developer Toolsfor macOS. All other dependencies will be installed automatically by themambaenvcreate-fenvironment.yml command.

If you want to use the system Python andpip, you will need:

  • C and C++ compilers (typically GCC).

  • Python header files (typically a package namedpython3-dev orpython3-devel)

  • BLAS and LAPACK libraries.OpenBLASis the NumPy default; other variants include Apple Accelerate,MKL,ATLAS andNetlib (or “Reference”)BLAS and LAPACK.

  • pkg-config for dependency detection.

  • A Fortran compiler is needed only for running thef2py tests. Theinstructions below include a Fortran compiler, however you can safelyleave it out.

To install NumPy build requirements, you can do:

sudoaptinstall-ygccg++gfortranlibopenblas-devliblapack-devpkg-configpython3-pippython3-dev

Alternatively, you can do:

sudoaptbuild-depnumpy

This command installs whatever is needed to build NumPy, with theadvantage that new dependencies or updates to required versions arehandled by the package managers.

To install NumPy build requirements, you can do:

sudodnfinstallgcc-gfortranpython3-developenblas-devellapack-develpkgconfig

Alternatively, you can do:

sudodnfbuilddepnumpy

This command installs whatever is needed to build NumPy, with theadvantage that new dependencies or updates to required versions arehandled by the package managers.

To install NumPy build requirements, you can do:

sudoyuminstallgcc-gfortranpython3-developenblas-devellapack-develpkgconfig

Alternatively, you can do:

sudoyum-builddepnumpy

This command installs whatever is needed to build NumPy, with theadvantage that new dependencies or updates to required versions arehandled by the package managers.

To install NumPy build requirements, you can do:

sudopacman-Sgcc-fortranopenblaspkgconf

Install Apple Developer Tools. An easy way to do this is toopen a terminal window,enter the command:

xcode-select--install

and follow the prompts. Apple Developer Tools includes Git, the Clang C/C++compilers, and other development utilities that may be required.

Donot use the macOS system Python. Instead, install Pythonwiththe python.org installer orwith a package manager like Homebrew, MacPorts or Fink.

On macOS >=13.3, the easiest build option is to use Accelerate, which isalready installed and will be automatically used by default.

On older macOS versions you need a different BLAS library, most likelyOpenBLAS, plus pkg-config to detect OpenBLAS. These are easiest to installwithHomebrew:

brewinstallopenblaspkg-configgfortran

On Windows, the use of a Fortran compiler is more tricky than on otherplatforms, because MSVC does not support Fortran, and gfortran and MSVCcan’t be used together. If you don’t need to run thef2py tests, simplyusing MSVC is easiest. Otherwise, you will need one of these sets ofcompilers:

  1. MSVC + Intel Fortran (ifort)

  2. Intel compilers (icc,ifort)

  3. Mingw-w64 compilers (gcc,g++,gfortran)

Compared to macOS and Linux, building NumPy on Windows is a little moredifficult, due to the need to set up these compilers. It is not possible tojust call a one-liner on the command prompt as you would on otherplatforms.

First, install Microsoft Visual Studio - the 2019 Community Edition or anynewer version will work (see theVisual Studio download site).This is needed even if you use the MinGW-w64 or Intel compilers, in orderto ensure you have the Windows Universal C Runtime (the other components ofVisual Studio are not needed when using Mingw-w64, and can be deselected ifdesired, to save disk space). The recommended version of the UCRT is>= 10.0.22621.0.

The MSVC installer does not put the compilers on the system path, andthe install location may change. To query the install location, MSVCcomes with avswhere.exe command-line utility. And to make theC/C++ compilers available inside the shell you are using, you need torun a.bat file for the correct bitness and architecture (e.g., for64-bit Intel CPUs, usevcvars64.bat).

If using a Conda environment while a version of Visual Studio 2019+ isinstalled that includes the MSVC v142 package (VS 2019 C++ x86/x64build tools), activating the conda environment should cause VisualStudio to be found and the appropriate .bat file executed to setthese variables.

For detailed guidance, seeUse the Microsoft C++ toolset from the command line.

Similar to MSVC, the Intel compilers are designed to be used with anactivation script (Intel\oneAPI\setvars.bat) that you run in theshell you are using. This makes the compilers available on the path.For detailed guidance, seeGet Started with the Intel® oneAPI HPC Toolkit for Windows.

There are several sources of binaries for MinGW-w64. We recommend theRTools versions, which can be installed with Chocolatey (seeChocolatey install instructionshere):

chocoinstallrtools-y--no-progress--force--version=4.0.0.20220206

Note

Compilers should be on the system path (i.e., thePATH environmentvariable should contain the directory in which the compiler executablescan be found) in order to be found, with the exception of MSVC whichwill be found automatically if and only if there are no other compilerson thePATH. You can use any shell (e.g., Powershell,cmd orGit Bash) to invoke a build. To check that this is the case, tryinvoking a Fortran compiler in the shell you use (e.g.,gfortran--version orifort--version).

Warning

When using a conda environment it is possible that the environmentcreation will not work due to an outdated Fortran compiler. If thathappens, remove thecompilers entry fromenvironment.yml andtry again. The Fortran compiler should be installed as described inthis section.

In Windows on ARM64, the set of a compiler options that are available forbuilding NumPy are limited. Compilers such as GCC and GFortran are not yetsupported for Windows on ARM64. Currently, the NumPy build for Windows on ARM64is supported with MSVC and LLVM toolchains. The use of a Fortran compiler ismore tricky than on other platforms, because MSVC does not support Fortran, andgfortran and MSVC can’t be used together. If you don’t need to run thef2pytests, simply using MSVC is easiest. Otherwise, you will need the followingset of compilers:

  1. MSVC + flang (cl,flang)

  2. LLVM + flang (clang-cl,flang)

First, install Microsoft Visual Studio - the 2022 Community Edition willwork (see theVisual Studio download site).Ensure that you have installed necessary Visual Studio components for building NumPyon WoA fromhere.

To use the flang compiler for Windows on ARM64, install Latest LLVMtoolchain for WoA fromhere.

The MSVC installer does not put the compilers on the system path, andthe install location may change. To query the install location, MSVCcomes with avswhere.exe command-line utility. And to make theC/C++ compilers available inside the shell you are using, you need torun a.bat file for the correct bitness and architecture (e.g., forARM64-based CPUs, usevcvarsarm64.bat).

For detailed guidance, seeUse the Microsoft C++ toolset from the command line.

Similar to MSVC, LLVM does not put the compilers on the system path.To set system path for LLVM compilers, users may need to usesetcommand to put compilers on the system path. To check compiler’s pathfor LLVM’s clang-cl, try invoking LLVM’s clang-cl compiler in the shell you use(clang-cl--version).

Note

Compilers should be on the system path (i.e., thePATH environmentvariable should contain the directory in which the compiler executablescan be found) in order to be found, with the exception of MSVC whichwill be found automatically if and only if there are no other compilerson thePATH. You can use any shell (e.g., Powershell,cmd orGit Bash) to invoke a build. To check that this is the case, tryinvoking a Fortran compiler in the shell you use (e.g.,flang--version).

Warning

Currently, Conda environment is not yet supported officially onWindowson ARM64.The present approach uses virtualenv for building NumPy from source onWindows on ARM64.

Building NumPy from source#

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

Note

If you don’t have a conda installation yet, we recommend usingMiniforge; any conda flavor will work though.

Building from source to use NumPy#

If you are using a conda environment,pip is still the tool you use toinvoke a from-source build of NumPy. It is important to always use the--no-build-isolation flag to thepipinstall command, to avoidbuilding against anumpy wheel from PyPI. In order for that to work youmust first install the remaining build dependencies into the condaenvironment:

# Either install all NumPy dev dependencies into a fresh conda environmentmambaenvcreate-fenvironment.yml# Or, install only the required build dependenciesmambainstallpythonnumpycythoncompilersopenblasmeson-pythonpkg-config# To build the latest stable release:pipinstallnumpy--no-build-isolation--no-binarynumpy# To build a development version, you need a local clone of the NumPy git repository:gitclonehttps://github.com/numpy/numpy.gitcdnumpygitsubmoduleupdate--initpipinstall.--no-build-isolation

Warning

On Windows, the AR, LD, and LDFLAGS environment variables may be set,which will cause the pip install command to fail. These variables are onlyneeded for flang and can be safely unset prior to running pip install.

# To build the latest stable release:pipinstallnumpy--no-binarynumpy# To build a development version, you need a local clone of the NumPy git repository:gitclonehttps://github.com/numpy/numpy.gitcdnumpygitsubmoduleupdate--initpipinstall.

Building from source for NumPy development#

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

gitclonehttps://github.com/numpy/numpy.gitcdnumpygitsubmoduleupdate--init

Then you want to do the following:

  1. Create a dedicated development environment (virtual environment or condaenvironment),

  2. Install all needed dependencies (build, and alsotest,doc andoptional dependencies),

  3. Build NumPy with thespin developer interface.

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

To create anumpy-dev development environment with every required andoptional dependency installed, run:

mambaenvcreate-fenvironment.ymlmambaactivatenumpy-dev

Note

There are many tools to manage virtual environments, likevenv,virtualenv/virtualenvwrapper,pyenv/pyenv-virtualenv,Poetry, PDM, Hatch, and more. Here we use the basicvenv tool thatis part of the Python stdlib. You can use any other tool; all we need isan activated Python environment.

Create and activate a virtual environment in a new directory namedvenv (note that the exact activation command may be different based on your OS and shell- see“How venvs work”in thevenv docs).

python-mvenvvenvsourcevenv/bin/activate
python-mvenvvenvsourcevenv/bin/activate
python-mvenvvenv.\venv\Scripts\activate
python-mvenvvenv.\venv\Scripts\activate

Note

Building NumPy with BLAS and LAPACK functions requires OpenBLASlibrary at Runtime. In Windows on ARM64, this can be done by settingup pkg-config for OpenBLAS dependency. The build steps for OpenBLASfor Windows on ARM64 can be foundhere.

Then install the Python-level dependencies from PyPI with:

python-mpipinstall-rrequirements/build_requirements.txt

To build NumPy in an activated development environment, run:

spinbuild

This will install NumPy inside the repository (by default in abuild-install directory). You can then run tests (spintest),drop into IPython (spinipython), or take other development stepslike build the html documentation or running benchmarks. Thespininterface is self-documenting, so please seespin--help andspin<subcommand>--help for detailed guidance.

Warning

In an activated conda environment on Windows, the AR, LD, and LDFLAGSenvironment variables may be set, which will cause the build to fail.These variables are only needed for flang and can be safely unsetfor build.

IDE support & editable installs

While thespin interface is our recommended way of working on NumPy,it has one limitation: because of the custom install location, NumPyinstalled usingspin will not be recognized automatically within anIDE (e.g., for running a script via a “run” button, or setting breakpointsvisually). This will work better with anin-place build (or “editableinstall”).

Editable installs are supported. It is important to understand thatyoumay use either an editable install orspinin a given repository clone,but not both. If you use editable installs, you have to usepytestand other development tools directly instead of usingspin.

To use an editable install, ensure you start from a clean repository (rungitclean-xdf if you’ve built withspin before) and have alldependencies set up correctly as described higher up on this page. Thendo:

# Note: the --no-build-isolation is important!pipinstall-e.--no-build-isolation# To run the tests for, e.g., the `numpy.linalg` module:pytestnumpy/linalg

When making changes to NumPy code, including to compiled code, there is noneed to manually rebuild or reinstall. NumPy is automatically rebuilt eachtime NumPy is imported by the Python interpreter; see themeson-pythondocumentation on editable installs for more details on how that works underthe hood.

When you rungitclean-xdf, which removes the built extension modules,remember to also uninstall NumPy withpipuninstallnumpy.

Warning

Note that editable installs are fundamentally incomplete installs.Their only guarantee is thatimportnumpy works - so they aresuitable for working on NumPy itself, and for working on pure Pythonpackages that depend on NumPy. Headers, entrypoints, and other suchthings may not be available from an editable install.

Customizing builds#

Background information#