This document aims to explain some best practices for authoring a package that depends on NumPy.
Understanding NumPy’s versioning and API/ABI stability
NumPy uses a standard,
compliant, versioning scheme: major.minor.bugfix. A major release is highly unusual and if it happens it will most likely indicate an ABI break. NumPy 1.xx releases happened from 2006 to 2023; NumPy 2.0 in early 2024 is the first release which changed the ABI (minor ABI breaks for corner cases may have happened a few times in minor releases). Minor versions are released regularly, typically every 6 months. Minor versions contain new features, deprecations, and removals of previously deprecated code. Bugfix releases are made even more frequently; they do not contain any new features or deprecations.
It is important to know that NumPy, like Python itself and most other well known scientific Python projects, does not use semantic versioning. Instead, backward incompatible API changes require deprecation warnings for at least two releases. For more details, see
NEP 23 — Backwards compatibility and deprecation policy
.
NumPy provides both a Python API and a C-API. The C-API can be accessed directly or through tools like Cython or f2py. If your package uses the NumPy C-API, it will generally be backward compatible with all relevant older NumPy versions and forward compatible within the same major NumPy version. For more details, for example if you wish to use API added in newer NumPy versions, see
.
Modules can also be safely built against NumPy 2.0 or later in
, which allows building against a single (minimum-supported) version of Python but be forward compatible with higher versions in the same series (e.g., 3.x). This can greatly reduce the number of wheels that need to be built and distributed. For more information and examples, see the
.
Testing against the NumPy main branch or pre-releases
For large, actively maintained packages that depend on NumPy, we recommend testing against the development version of NumPy in CI. To make this easy, nightly builds are provided as wheels at
https://anaconda.org/scientific-python-nightly-wheels/
. Example install command:
pipinstall-U--pre--only-binary:all:-ihttps://pypi.anaconda.org/scientific-python-nightly-wheels/simplenumpyThis helps detect regressions in NumPy that need fixing before the next NumPy release. Furthermore, we recommend to raise errors on warnings in CI for this job, either all warnings or otherwise at least DeprecationWarning and FutureWarning. This gives you an early warning about changes in NumPy to adapt your code.
If you want to test your own wheel builds against the latest NumPy nightly build and you’re using cibuildwheel, you may need something like this in your CI config file:
CIBW_ENVIRONMENT:"PIP_PRE=1 PIP_EXTRA_INDEX_URL=https://pypi.anaconda.org/scientific-python-nightly-wheels/simple"Adding a dependency on NumPy
Build-time dependency
Note
Before NumPy 1.25, the NumPy C-API was not exposed in a backward compatible way by default. This means that when compiling with a NumPy version earlier than 1.25 you have to compile with the oldest version you wish to support. This can be done by using
. Please see the
.
If a package either uses the NumPy C-API directly or it uses some other tool that depends on it like Cython or Pythran, NumPy is a build-time dependency of the package.
By default, NumPy exposes an API that is backward compatible with the earliest NumPy version that supports the oldest Python version currently supported by NumPy. For example, NumPy 1.25.0 supports Python 3.9 and above; and the earliest NumPy version to support Python 3.9 was 1.19. Therefore we guarantee NumPy 1.25 will, when using defaults, expose a C-API compatible with NumPy 1.19. (the exact version is set within NumPy-internal header files).
NumPy is also forward compatible for all minor releases, but a major release is expected to require recompilation (see
further down).
The default behavior can be customized for example by adding:
#define NPY_TARGET_VERSION NPY_1_22_API_VERSIONbefore including any NumPy headers (or the equivalent -D compiler flag) in every extension module that requires the NumPy C-API. This is mainly useful if you need to use newly added API at the cost of not being compatible with older versions.
If for some reason you wish to compile for the currently installed NumPy version by default you can add:
#ifndef NPY_TARGET_VERSION#define NPY_TARGET_VERSION NPY_API_VERSION#endifWhich allows a user to override the default via -DNPY_TARGET_VERSION. This define must be consistent for each extension module (use of import_array()) and also applies to the umath module.
When you compile against NumPy, you should add the proper version restrictions to your pyproject.toml (see PEP 517). Since your extension will not be compatible with a new major release of NumPy and may not be compatible with very old versions.
For conda-forge packages, please see
for instructions on how to declare a dependency on numpy when using the C API.
Runtime dependency & version ranges
NumPy itself and many core scientific Python packages have agreed on a schedule for dropping support for old Python and NumPy versions:
. We recommend all packages depending on NumPy to follow the recommendations in NEP 29.
For run-time dependencies, specify version bounds in pyproject.toml.
Most libraries that rely on NumPy will not need to set an upper version bound: NumPy is careful to preserve backward-compatibility.
That said, if you are (a) a project that is guaranteed to release frequently, (b) use a large part of NumPy’s API surface, and (c) is worried that changes in NumPy may break your code, you can set an upper bound of <MAJOR.MINOR+N with N no less than 3, and MAJOR.MINOR being the current release of NumPy.
If you use the NumPy C-API (directly or via Cython), you can also pin the current major version to prevent ABI breakage. Note that setting an upper bound on NumPy may
affect the ability of your library to be installed alongside other, newer packages
.
Note
SciPy has more documentation on how it builds wheels and deals with its build-time and runtime dependencies
.
NumPy and SciPy wheel build CI may also be useful as a reference, it can be found
and
.
NumPy 2.0 ABI handling
NumPy 2.0 changed the C ABI. The important rule for binary wheels is:
Wheels built against NumPy 1.xx will not work with NumPy 2.0 or later.
Wheels built against NumPy 2.x will work with NumPy 1.xx at runtime. How old NumPy versions are supported can be customized with NPY_TARGET_VERSION, see
.
If your package uses the NumPy C-API (directly or via Cython), you need to rebuild and release wheels compiled against NumPy 2.x. Pure Python packages may also need code updates; see
.
There are two common cases:
Keep compatibility with NumPy 1.xx and 2.x
Build against NumPy 2.x, but keep a lower runtime bound. For example, to support NumPy 1.23.5 and up:
[build-system]build-backend=...requires=["numpy>=2.0",...][project]dependencies=["numpy>=1.23.5",]Support NumPy 2.x only
This is simpler, but more restrictive for your users:
[build-system]build-backend=...requires=["numpy>=2.0",...][project]dependencies=["numpy>=2.0",]We recommend at least one CI job that builds a wheel and then tests it against the oldest NumPy version you support. For example:
-name:Build wheel, then install itrun:|python -m buildpython -m pip install dist/*.whl-name:Test against oldest supported NumPy versionrun:|python -m pip install numpy==1.23.5# now run test suiteTo test against unreleased NumPy versions, use a nightly build (see
) or build NumPy from source.