These instructions give an overview of what is necessary to build binary releases for NumPy.
Useful info can be found in the following locations:
- Source tree
- NumPy docs
- Release scripts
:ref:`NEP 29 <NEP29>` outlines which Python versions are supported; For the first half of 2020, this will be Python >= 3.6. We test NumPy against all these versions every time we merge code to main. Binary installers may be available for a subset of these versions (see below).
OS X
OS X versions >= 10.9 are supported, for Python version support see :ref:`NEP 29 <NEP29>`. We build binary wheels for OSX that are compatible with Python.org Python, system Python, homebrew and macports - see this OSX wheel building summary for details.
Windows
We build 32- and 64-bit wheels on Windows. Windows 7, 8 and 10 are supported. We build NumPy using the mingw-w64 toolchain, cibuildwheels and GitHub actions.
Linux
We build and ship manylinux2014 wheels for NumPy. Many Linux distributions include their own binary builds of NumPy.
BSD / Solaris
No binaries are provided, but successful builds on Solaris and BSD have been reported.
We build all our wheels on cloud infrastructure - so this list of compilers is
for information and debugging builds locally. See the .travis.yml
script
in the numpy wheels repo for an outdated source of the build recipes using
multibuild.
The same gcc version is used as the one with which Python itself is built on each platform. At the moment this means:
- OS X builds on travis currently use clang. It appears that binary wheels for OSX >= 10.6 can be safely built from the travis-ci OSX 10.9 VMs when building against the Python from the Python.org installers;
- Windows builds use the mingw-w64 toolchain;
- Manylinux2014 wheels use the gcc provided on the Manylinux docker images.
You will need Cython for building the binaries. Cython compiles the .pyx
files in the NumPy distribution to .c
files.
All the wheels link to a version of OpenBLAS supplied via the openblas-libs repo. The shared object (or DLL) is shipped with in the wheel, renamed to prevent name collisions with other OpenBLAS shared objects that may exist in the filesystem.
The NumPy wheels and sdist are now built using cibuildwheel with github actions.
We are no longer building PDF
files. All that will be needed is
- virtualenv (pip).
The other requirements will be filled automatically during the documentation build process.
The only application needed for uploading is
- twine (pip).
You will also need a PyPI token, which is best kept on a keyring. See the twine keyring documentation for how to do that.
You will need a personal access token https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ so that scripts can access the github NumPy repository.
- gitpython (pip)
- pygithub (pip)
- Wheels
We currently support Python 3.8-3.10 on Windows, OSX, and Linux.
- Windows: 32-bit and 64-bit wheels built using Github actions;
- OSX: x64_86 and arm64 OSX wheels built using Github actions;
- Linux: x64_86 and aarch64 Manylinux2014 wheels built using Github actions.
- Other Release notes and changelog
- Source distribution We build source releases in the .tar.gz format.
A typical release schedule is one beta, two release candidates and a final release. It's best to discuss the timing on the mailing list first, in order for people to get their commits in on time, get doc wiki edits merged, etc. After a date is set, create a new maintenance/x.y.z branch, add new empty release notes for the next version in the main branch and update the Trac Milestones.
The CI builds wheels when a PR header begins with REL
. Your last
PR before releasing should be so marked and all the tests should pass.
You can also do:
git clean -fxdq python setup.py bdist_wheel python setup.py sdist
For details of the build process itself, it is best to read the Step-by-Step Directions below.
Note
The following steps are repeated for the beta(s), release candidates(s) and the final release.
Before :ref:`the release branch is made <branching>`, it should be checked that all deprecated code that should be removed is actually removed, and all new deprecations say in the docstring or deprecation warning what version the code will be removed.
The C API version needs to be tracked in three places
- numpy/_core/meson.build
- numpy/_core/code_generators/cversions.txt
- numpy/_core/include/numpy/numpyconfig.h
There are three steps to the process.
If the API has changed, increment the C_API_VERSION in numpy/core/meson.build. The API is unchanged only if any code compiled against the current API will be backward compatible with the last released NumPy version. Any changes to C structures or additions to the public interface will make the new API not backward compatible.
If the C_API_VERSION in the first step has changed, or if the hash of the API has changed, the cversions.txt file needs to be updated. To check the hash, run the script numpy/_core/cversions.py and note the API hash that is printed. If that hash does not match the last hash in numpy/_core/code_generators/cversions.txt the hash has changed. Using both the appropriate C_API_VERSION and hash, add a new entry to cversions.txt. If the API version was not changed, but the hash differs, you will need to comment out the previous entry for that API version. For instance, in NumPy 1.9 annotations were added, which changed the hash, but the API was the same as in 1.8. The hash serves as a check for API changes, but it is not definitive.
If steps 1 and 2 are done correctly, compiling the release should not give a warning "API mismatch detect at the beginning of the build".
The numpy/_core/include/numpy/numpyconfig.h will need a new NPY_X_Y_API_VERSION macro, where X and Y are the major and minor version numbers of the release. The value given to that macro only needs to be increased from the previous version if some of the functions or macros in the include files were deprecated.
The C ABI version number in numpy/_core/meson.build should only be updated for a major release.
Use towncrier to build the release note and
commit the changes. This will remove all the fragments from
doc/release/upcoming_changes
and add doc/release/<version>-note.rst
.:
towncrier build --version "<version>" git commit -m"Create release note"
Check that the release notes are up-to-date.
Update the release notes with a Highlights section. Mention some of the following:
- major new features
- deprecated and removed features
- supported Python versions
- for SciPy, supported NumPy version(s)
- outlook for the near future