NumPy 2.1.0 Release Notes#
NumPy 2.1.0 provides support for the upcoming Python 3.13 release and drops support for Python 3.9. In addition to the usual bug fixes and updated Python support, it helps get us back into our usual release cycle after the extended development of 2.0. The highlights for this release are:
Support for the array-api 2023.12 standard.
Support for Python 3.13.
Preliminary support for free threaded Python 3.13.
Python versions 3.10-3.13 are supported in this release.
New functions#
New function numpy.unstack
#
A new function np.unstack(array, axis=...)
was added, which splits
an array into a tuple of arrays along an axis. It serves as the inverse
of numpy.stack
.
(gh-26579)
Deprecations#
The
fix_imports
keyword argument innumpy.save
is deprecated. Since NumPy 1.17,numpy.save
uses a pickle protocol that no longer supports Python 2, and ignoredfix_imports
keyword. This keyword is kept only for backward compatibility. It is now deprecated.(gh-26452)
Passing non-integer inputs as the first argument of
bincount
is now deprecated, because such inputs are silently cast to integers with no warning about loss of precision.(gh-27076)
Expired deprecations#
C API changes#
Many shims removed from npy_3kcompat.h#
Many of the old shims and helper functions were removed from
npy_3kcompat.h
. If you find yourself in need of these, vendor the previous
version of the file into your codebase.
(gh-26842)
New PyUFuncObject
field process_core_dims_func
#
The field process_core_dims_func
was added to the structure
PyUFuncObject
. For generalized ufuncs, this field can be set to a function
of type PyUFunc_ProcessCoreDimsFunc
that will be called when the ufunc is
called. It allows the ufunc author to check that core dimensions satisfy
additional constraints, and to set output core dimension sizes if they have not
been provided.
(gh-26908)
New Features#
Preliminary Support for Free-Threaded CPython 3.13#
CPython 3.13 will be available as an experimental free-threaded build. See https://py-free-threading.github.io, PEP 703 and the CPython 3.13 release notes for more detail about free-threaded Python.
NumPy 2.1 has preliminary support for the free-threaded build of CPython 3.13. This support was enabled by fixing a number of C thread-safety issues in NumPy. Before NumPy 2.1, NumPy used a large number of C global static variables to store runtime caches and other state. We have either refactored to avoid the need for global state, converted the global state to thread-local state, or added locking.
Support for free-threaded Python does not mean that NumPy is thread
safe. Read-only shared access to ndarray should be safe. NumPy exposes shared
mutable state and we have not added any locking to the array object itself to
serialize access to shared state. Care must be taken in user code to avoid
races if you would like to mutate the same array in multiple threads. It is
certainly possible to crash NumPy by mutating an array simultaneously in
multiple threads, for example by calling a ufunc and the resize
method
simultaneously. For now our guidance is: “don’t do that”. In the future we would
like to provide stronger guarantees.
Object arrays in particular need special care, since the GIL previously provided locking for object array access and no longer does. See Issue #27199 for more information about object arrays in the free-threaded build.
If you are interested in free-threaded Python, for example because you have a multiprocessing-based workflow that you are interested in running with Python threads, we encourage testing and experimentation.
If you run into problems that you suspect are because of NumPy, please open an issue, checking first if the bug also occurs in the “regular” non-free-threaded CPython 3.13 build. Many threading bugs can also occur in code that releases the GIL; disabling the GIL only makes it easier to hit threading bugs.
(gh-26157)
numpy.reshape
andnumpy.ndarray.reshape
now supportshape
andcopy
arguments.(gh-26292)
NumPy now supports DLPack v1, support for older versions will be deprecated in the future.
(gh-26501)
numpy.asanyarray
now supportscopy
anddevice
arguments, matchingnumpy.asarray
.(gh-26580)
numpy.printoptions
,numpy.get_printoptions
, andnumpy.set_printoptions
now support a new option,override_repr
, for defining customrepr(array)
behavior.(gh-26611)
numpy.cumulative_sum
andnumpy.cumulative_prod
were added as Array API compatible alternatives fornumpy.cumsum
andnumpy.cumprod
. The new functions can include a fixed initial (zeros forsum
and ones forprod
) in the result.(gh-26724)
numpy.clip
now supportsmax
andmin
keyword arguments which are meant to replacea_min
anda_max
. Also, fornp.clip(a)
ornp.clip(a, None, None)
a copy of the input array will be returned instead of raising an error.(gh-26724)
numpy.astype
now supportsdevice
argument.(gh-26724)
f2py
can generate freethreading-compatible C extensions#
Pass --freethreading-compatible
to the f2py CLI tool to produce a C
extension marked as compatible with the free threading CPython
interpreter. Doing so prevents the interpreter from re-enabling the GIL at
runtime when it imports the C extension. Note that f2py
does not analyze
fortran code for thread safety, so you must verify that the wrapped fortran
code is thread safe before marking the extension as compatible.
(gh-26981)
Improvements#
histogram
auto-binning now returns bin sizes >=1 for integer input data#
For integer input data, bin sizes smaller than 1 result in spurious empty
bins. This is now avoided when the number of bins is computed using one of the
algorithms provided by histogram_bin_edges
.
(gh-12150)
ndarray
shape-type parameter is now covariant and bound to tuple[int, ...]
#
Static typing for ndarray
is a long-term effort that continues
with this change. It is a generic type with type parameters for
the shape and the data type. Previously, the shape type parameter could be
any value. This change restricts it to a tuple of ints, as one would expect
from using ndarray.shape
. Further, the shape-type parameter has been
changed from invariant to covariant. This change also applies to the subtypes
of ndarray
, e.g. numpy.ma.MaskedArray
. See the
typing docs
for more information.
(gh-26081)
np.quantile
with method closest_observation
chooses nearest even order statistic#
This changes the definition of nearest for border cases from the nearest odd order statistic to nearest even order statistic. The numpy implementation now matches other reference implementations.
(gh-26656)
lapack_lite
is now thread safe#
NumPy provides a minimal low-performance version of LAPACK named lapack_lite
that can be used if no BLAS/LAPACK system is detected at build time.
Until now, lapack_lite
was not thread safe. Single-threaded use cases did
not hit any issues, but running linear algebra operations in multiple threads
could lead to errors, incorrect results, or segfaults due to data races.
We have added a global lock, serializing access to lapack_lite
in multiple
threads.
(gh-26750)
The numpy.printoptions
context manager is now thread and async-safe#
In prior versions of NumPy, the printoptions were defined using a combination
of Python and C global variables. We have refactored so the state is stored in
a python ContextVar
, making the context manager thread and async-safe.
(gh-26846)
Type hinting numpy.polynomial
#
Starting from the 2.1 release, PEP 484 type annotations have been included for
the functions and convenience classes in numpy.polynomial
and its
sub-packages.
(gh-26897)
Improved numpy.dtypes
type hints#
The type annotations for numpy.dtypes
are now a better reflection of the
runtime: The numpy.dtype
type-aliases have been replaced with specialized
dtype
subtypes, and the previously missing annotations for
numpy.dtypes.StringDType
have been added.
(gh-27008)
Performance improvements and changes#
numpy.save
now uses pickle protocol version 4 for saving arrays with object dtype, which allows for pickle objects larger than 4GB and improves saving speed by about 5% for large arrays.(gh-26388)
OpenBLAS on x86_64 and i686 is built with fewer kernels. Based on benchmarking, there are 5 clusters of performance around these kernels:
PRESCOTT NEHALEM SANDYBRIDGE HASWELL SKYLAKEX
.(gh-27147)
OpenBLAS on windows is linked without quadmath, simplifying licensing
(gh-27147)
Due to a regression in OpenBLAS on windows, the performance improvements when using multiple threads for OpenBLAS 0.3.26 were reverted.
(gh-27147)
ma.cov
and ma.corrcoef
are now significantly faster#
The private function has been refactored along with ma.cov
and
ma.corrcoef
. They are now significantly faster, particularly on large,
masked arrays.
(gh-26285)
Changes#
As
numpy.vecdot
is now a ufunc it has a less precise signature. This is due to the limitations of ufunc’s typing stub.(gh-26313)
numpy.floor
,numpy.ceil
, andnumpy.trunc
now won’t perform casting to a floating dtype for integer and boolean dtype input arrays.(gh-26766)
ma.corrcoef
may return a slightly different result#
A pairwise observation approach is currently used in ma.corrcoef
to
calculate the standard deviations for each pair of variables. This has been
changed as it is being used to normalise the covariance, estimated using
ma.cov
, which does not consider the observations for each variable in a
pairwise manner, rendering it unnecessary. The normalisation has been replaced
by the more appropriate standard deviation for each variable, which
significantly reduces the wall time, but will return slightly different
estimates of the correlation coefficients in cases where the observations
between a pair of variables are not aligned. However, it will return the same
estimates in all other cases, including returning the same correlation matrix
as corrcoef
when using a masked array with no masked values.
(gh-26285)
Cast-safety fixes in copyto
and full
#
copyto
now uses NEP 50 correctly and applies this to its cast safety.
Python integer to NumPy integer casts and Python float to NumPy float casts
are now considered “safe” even if assignment may fail or precision may be lost.
This means the following examples change slightly:
np.copyto(int8_arr, 1000)
previously performed an unsafe/same-kind castof the Python integer. It will now always raise, to achieve an unsafe cast you must pass an array or NumPy scalar.
np.copyto(uint8_arr, 1000, casting="safe")
will raise an OverflowError rather than a TypeError due to same-kind casting.np.copyto(float32_arr, 1e300, casting="safe")
will overflow toinf
(float32 cannot hold1e300
) rather raising a TypeError.
Further, only the dtype is used when assigning NumPy scalars (or 0-d arrays), meaning that the following behaves differently:
np.copyto(float32_arr, np.float64(3.0), casting="safe")
raises.np.coptyo(int8_arr, np.int64(100), casting="safe")
raises. Previously, NumPy checked whether the 100 fits theint8_arr
.
This aligns copyto
, full
, and full_like
with the correct NumPy 2
behavior.
(gh-27091)