github numpy/numpy v1.21.0rc1

latest releases: v1.24.0.dev0, v1.22.4, v1.21.6...
pre-release12 months ago

NumPy 1.21.0 Release Notes

The NumPy 1.21.0 release highlights are

  • continued SIMD work covering more functions and platforms,
  • initial work on the new dtype infrastructure and casting,
  • improved documentation,
  • improved annotations,
  • the new PCG64DXSM bitgenerator for random numbers.

In addition there are the usual large number of bug fixes and other

The Python versions supported for this release are 3.7-3.9. Official
support for Python 3.10 will be added when it is released.

New functions

Add PCG64DXSM BitGenerator

Uses of the PCG64 BitGenerator in a massively-parallel context have
been shown to have statistical weaknesses that were not apparent at the
first release in numpy 1.17. Most users will never observe this weakness
and are safe to continue to use PCG64. We have introduced a new
PCG64DXSM BitGenerator that will eventually become the new default
BitGenerator implementation used by default_rng in future releases.
PCG64DXSM solves the statistical weakness while preserving the
performance and the features of PCG64.

See upgrading-pcg64{.interpreted-text role="ref"} for more details.


Expired deprecations

  • The shape argument of numpy.unravel_index cannot be
    passed as dims keyword argument anymore. (Was deprecated in NumPy


  • The function PyUFunc_GenericFunction has been disabled. It was
    deprecated in NumPy 1.19. Users should call the ufunc directly using
    the Python API.


  • The function PyUFunc_SetUsesArraysAsData has been disabled. It was
    deprecated in NumPy 1.19.


  • The class PolyBase has been removed (deprecated in numpy 1.9.0).
    Please use the abstract ABCPolyBase class instead.


  • The unused PolyError and PolyDomainError exceptions are removed.



Inexact matches for numpy.convolve and numpy.correlate are deprecated

numpy.convolve and numpy.correlate now
emit a warning when there are case insensitive and/or inexact matches
found for mode argument in the functions. Pass full "same",
"valid", "full" strings instead of "s", "v", "f" for the
mode argument.


np.typeDict has been formally deprecated

np.typeDict is a deprecated alias for np.sctypeDict and has been so
for over 14 years (6689502).
A deprecation warning will now be issued whenever getting np.typeDict.


Exceptions will be raised during array-like creation

When an object raised an exception during access of the special
attributes __array__ or __array_interface__, this exception was
usually ignored. A warning is now given when the exception is anything
but AttributeError. To silence the warning, the type raising the
exception has to be adapted to raise an AttributeError.


Four ndarray.ctypes methods have been deprecated

Four methods of the ndarray.ctypes object have been
deprecated, as they are (undocumentated) implementation artifacts of
their respective properties.

The methods in question are:

  • _ctypes.get_data (use instead)
  • _ctypes.get_shape (use _ctypes.shape instead)
  • _ctypes.get_strides (use _ctypes.strides instead)
  • _ctypes.get_as_parameter (use _ctypes._as_parameter_ instead)


Future Changes

Promotion of strings with numbers and bools will be deprecated

Any promotion of numbers and strings is deprecated and will give a
FutureWarning the main affected functionalities are:

  • numpy.promote_types and
    numpy.result_type which will raise an error in this
    case in the future.
  • numpy.concatenate will raise an error when
    concatenating a string and numeric array. You can use dtype="S" to
    explicitly request a string result.
  • numpy.array and related functions will start
    returning object arrays because these functions use object as a
    fallback when no common dtype can be found. However, it may happen
    that future releases of NumPy will generally error in these cases.

This will mainly affect code such as:

np.asarray(['string', 0])


np.concatenate((['string'], [0]))

in both cases adding dtype="U" or dtype="S" will give the previous
(string) result, while dtype=object will ensure an array with object
dtype is returned.

Comparisons, universal functions, and casting are not affected by this.


Compatibility notes

Error type changes in universal functions

The universal functions may now raise different errors on invalid input
in some cases. The main changes should be that a RuntimeError was
replaced with a more fitting TypeError. When multiple errors were
present in the same call, NumPy may now raise a different one.


__array_ufunc__ argument validation

NumPy will now partially validate arguments before calling
__array_ufunc__. Previously, it was possible to pass on invalid
arguments (such as a non-existing keyword argument) when dispatch was
known to occur.


__array_ufunc__ and additional positional arguments

Previously, all positionally passed arguments were checked for
__array_ufunc__ support. In the case of reduce, accumulate, and
reduceat all arguments may be passed by position. This means that when
they were passed by position, they could previously have been asked to
handle the ufunc call via __array_ufunc__. Since this depended on the
way the arguments were passed (by position or by keyword), NumPy will
now only dispatch on the input and output array. For example, NumPy will
never dispatch on the where array in a reduction such as


Validate input values in Generator.uniform

Checked that high - low >= 0 in np.random.Generator.uniform. Raises
ValueError if low > high. Previously out-of-order inputs were
accepted and silently swapped, so that if low > high, the value
generated was high + (low - high) * random().


/usr/include removed from default include paths

The default include paths when building a package with numpy.distutils
no longer include /usr/include. This path is normally added by the
compiler, and hardcoding it can be problematic. In case this causes a
problem, please open an issue. A workaround is documented in PR 18658.


Changes to comparisons with dtype=...

When the dtype= (or signature) arguments to comparison ufuncs
(equal, less, etc.) is used, this will denote the desired output
dtype in the future. This means that:

np.equal(2, 3, dtype=object)

will give a FutureWarning that it will return an object array in the
future, which currently happens for:

np.equal(None, None, dtype=object)

due to the fact that np.array(None) is already an object array. (This
also happens for some other dtypes.)

Since comparisons normally only return boolean arrays, providing any
other dtype will always raise an error in the future and give a
DeprecationWarning now.


Changes to dtype and signature arguments in ufuncs

The universal function arguments dtype and signature which are also
valid for reduction such as np.add.reduce (which is the implementation
for np.sum) will now issue a warning when the dtype provided is not
a "basic" dtype.

NumPy almost always ignored metadata, byteorder or time units on these
inputs. NumPy will now always ignore it and raise an error if byteorder
or time unit changed. The following are the most important examples of
changes which will give the error. In some cases previously the
information stored was not ignored, in all of these an error is now

# Previously ignored the byte-order (affect if non-native)
np.add(3, 5, dtype=">i32")

# The biggest impact is for timedelta or datetimes:
arr = np.arange(10, dtype="m8[s]")
# The examples always ignored the time unit "ns":
np.add(arr, arr, dtype="m8[ns]")
np.maximum.reduce(arr, dtype="m8[ns]")

# The following previously did use "ns" (as opposed to `arr.dtype`)
np.add(3, 5, dtype="m8[ns]")  # Now return generic time units
np.maximum(arr, arr, dtype="m8[ns]")  # Now returns "s" (from `arr`)

The same applies for functions like np.sum which use these internally.
This change is necessary to achieve consistent handling within NumPy.

If you run into these, in most cases pass for example
dtype=np.timedelta64 which clearly denotes a general timedelta64
without any unit or byte-order defined. If you need to specify the
output dtype precisely, you may do so by either casting the inputs or
providing an output array using out=.

NumPy may choose to allow providing an exact output dtype here in the
future, which would be preceded by a FutureWarning.


Ufunc signature=... and dtype= generalization and casting

The behaviour for np.ufunc(1.0, 1.0, signature=...) or
np.ufunc(1.0, 1.0, dtype=...) can now yield different loops in 1.21
compared to 1.20 because of changes in promotion. When signature was
previously used, the casting check on inputs was relaxed, which could
lead to downcasting inputs unsafely especially if combined with

Casting is now guaranteed to be safe. If a signature is only partially
provided, for example using signature=("float64", None, None), this
could lead to no loop being found (an error). In that case, it is
necessary to provide the complete signature to enforce casting the
inputs. If dtype="float64" is used or only outputs are set (e.g.
signature=(None, None, "float64") the is unchanged. We expect that
very few users are affected by this change.

Further, the meaning of dtype="float64" has been slightly modified and
now strictly enforces only the correct output (and not input) DTypes.
This means it is now always equivalent to:

signature=(None, None, "float64")

(If the ufunc has two inputs and one output). Since this could lead to
no loop being found in some cases, NumPy will normally also search for
the loop:

signature=("float64", "float64", "float64")

if the first search failed. In the future, this behaviour may be
customized to achieve the expected results for more complex ufuncs. (For
some universal functions such as np.ldexp inputs can have different


Distutils forces strict floating point model on clang

NumPy distutils will now always add the -ffp-exception-behavior=strict
compiler flag when compiling with clang. Clang defaults to a non-strict
version, which allows the compiler to generate code that does not set
floating point warnings/errors correctly.


C API changes

Use of ufunc->type_resolver and "type tuple"

NumPy now normalizes the "type tuple" argument to the type resolver
functions before calling it. Note that in the use of this type resolver
is legacy behaviour and NumPy will not do so when possible. Calling
ufunc->type_resolver or PyUFunc_DefaultTypeResolver is strongly
discouraged and will now enforce a normalized type tuple if done. Note
that this does not affect providing a type resolver, which is expected
to keep working in most circumstances. If you have an unexpected
use-case for calling the type resolver, please inform the NumPy
developers so that a solution can be found.


New Features

Added a mypy plugin for handling platform-specific numpy.number precisions

A mypy plugin is now available for
automatically assigning the (platform-dependent) precisions of certain
numpy.number subclasses, including the likes of
numpy.int_, numpy.intp and
numpy.longlong. See the documentation on
scalar types <arrays.scalars.built-in>{.interpreted-text role="ref"}
for a comprehensive overview of the affected classes.

Note that while usage of the plugin is completely optional, without it
the precision of above-mentioned classes will be inferred as

To enable the plugin, one must add it to their mypy configuration

plugins = numpy.typing.mypy_plugin


Let the mypy plugin manage extended-precision numpy.number subclasses

The mypy plugin, introduced in
numpy/numpy#17843, has
been expanded: the plugin now removes annotations for platform-specific
extended-precision types that are not available to the platform in
question. For example, it will remove numpy.float128
when not available.

Without the plugin all extended-precision types will, as far as mypy
is concerned, be available on all platforms.

To enable the plugin, one must add it to their mypy configuration

plugins = numpy.typing.mypy_plugin


New min_digits argument for printing float values

A new min_digits argument has been added to the dragon4 float printing
functions numpy.format_float_positional and
numpy.format_float_scientific . This kwd guarantees
that at least the given number of digits will be printed when printing
in unique=True mode, even if the extra digits are unnecessary to
uniquely specify the value. It is the counterpart to the precision
argument which sets the maximum number of digits to be printed. When
unique=False in fixed precision mode, it has no effect and the precision
argument fixes the number of digits.


f2py now recognizes Fortran abstract interface blocks

numpy.f2py can now parse abstract interface blocks.


BLAS and LAPACK configuration via environment variables

Autodetection of installed BLAS and LAPACK libraries can be bypassed by
using the NPY_BLAS_LIBS and NPY_LAPACK_LIBS environment variables.
Instead, the link flags in these environment variables will be used
directly, and the language is assumed to be F77. This is especially
useful in automated builds where the BLAS and LAPACK that are installed
are known exactly. A use case is replacing the actual implementation at
runtime via stub library links.

If NPY_CBLAS_LIBS is set (optional in addition to NPY_BLAS_LIBS),
this will be used as well, by defining HAVE_CBLAS and appending the
environment variable content to the link flags.


A runtime-subcriptable alias has been added for ndarray

numpy.typing.NDArray has been added, a runtime-subscriptable alias for
np.ndarray[Any, np.dtype[~Scalar]]. The new type alias can be used for
annotating arrays with a given dtype and unspecified shape. ^1^

^1^ NumPy does not support the annotating of array shapes as of 1.21,
this is expected to change in the future though (see
646{.interpreted-text role="pep"}).


>>> import numpy as np
>>> import numpy.typing as npt

>>> print(npt.NDArray)
numpy.ndarray[typing.Any, numpy.dtype[~ScalarType]]

>>> print(npt.NDArray[np.float64])
numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]

>>> NDArrayInt = npt.NDArray[np.int_]
>>> a: NDArrayInt = np.arange(10)

>>> def func(a: npt.ArrayLike) -> npt.NDArray[Any]:
...     return np.array(a)



Arbitrary period option for numpy.unwrap

The size of the interval over which phases are unwrapped is no longer
restricted to 2 * pi. This is especially useful for unwrapping
degrees, but can also be used for other intervals.

>>> phase_deg = np.mod(np.linspace(0,720,19), 360) - 180
>>> phase_deg
array([-180., -140., -100.,  -60.,  -20.,   20.,   60.,  100.,  140.,
       -180., -140., -100.,  -60.,  -20.,   20.,   60.,  100.,  140.,

>>> unwrap(phase_deg, period=360)
array([-180., -140., -100.,  -60.,  -20.,   20.,   60.,  100.,  140.,
        180.,  220.,  260.,  300.,  340.,  380.,  420.,  460.,  500.,


np.unique now returns single NaN

When np.unique operated on an array with multiple NaN entries, its
return included a NaN for each entry that was NaN in the original
array. This is now improved such that the returned array contains just
one NaN as the last element.

Also for complex arrays all NaN values are considered equivalent (no
matter whether the NaN is in the real or imaginary part). As the
representant for the returned array the smallest one in the
lexicographical order is chosen - see np.sort for how the
lexicographical order is defined for complex arrays.


Generator.rayleigh and Generator.geometric performance improved

The performance of Rayleigh and geometric random variate generation in
Generator has improved. These are both transformation of exponential
random variables and the slow log-based inverse cdf transformation has
been replaced with the Ziggurat-based exponential variate generator.

This change breaks the stream of variates generated when variates from
either of these distributions are produced.


Placeholder annotations have been improved

All placeholder annotations, that were previously annotated as
typing.Any, have been improved. Where appropiate they have been
replaced with explicit function definitions, classes or other
miscellaneous objects.


Performance improvements

Improved performance in integer division of NumPy arrays

Integer division of NumPy arrays now uses
libdivide when the divisor is a constant. With
the usage of libdivide and other minor optimizations, there is a large
speedup. The // operator and np.floor_divide makes use of the new


Improve performance of and np.load for small arrays is now a lot faster for small arrays.

np.load is also faster for small arrays, but only when serializing
with a version >= (3, 0).

Both are done by removing checks that are only relevant for Python 2,
while still maintaining compatibility with arrays which might have been
created by Python 2.



numpy.piecewise output class now matches the input class

When numpy.ndarray subclasses are used on input to
numpy.piecewise, they are passed on to the functions.
The output will now be of the same subclass as well.


Enable Accelerate Framework

With the release of macOS 11.3, several different issues that numpy was
encountering when using Accelerate Framework's implementation of BLAS
and LAPACK should be resolved. This change enables the Accelerate
Framework as an option on macOS. If additional issues are found, please
file a bug report against Accelerate using the developer feedback
assistant tool ( We intend
to address issues promptly and plan to continue supporting and updating
our BLAS and LAPACK libraries.




9ccf85701eb21a5ea2fb477136ab4247  numpy-1.21.0rc1-cp37-cp37m-macosx_10_9_x86_64.whl
5efabc4661fe181dc6e1c65ec635f469  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.whl
15dba3c0e6a1018d964101dd0da643f0  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
2d950f3681f6ca81446e1ef1ce965000  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
7f6754af0b06c1847a92430fb34f49ca  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.whl
26a2ed6c94f1e679e2356c2e34d5bca0  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.whl
f83946bc549f52967ad167770ce7f028  numpy-1.21.0rc1-cp37-cp37m-win32.whl
745946f9036969a4574f5dfcdbf73d00  numpy-1.21.0rc1-cp37-cp37m-win_amd64.whl
9aec39edd809b0ce0f024511ad670892  numpy-1.21.0rc1-cp38-cp38-macosx_10_9_x86_64.whl
11cce9128d4c41675383ff5ffebc5f80  numpy-1.21.0rc1-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.whl
b9baa8e1cc031b8f63122e056f5a9d01  numpy-1.21.0rc1-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
ed671703310ffc4a446c9a7b2227045c  numpy-1.21.0rc1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
77dfe86f5af5702c6115cec33211a5d0  numpy-1.21.0rc1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl
84971cae75e47951f451b889958220f7  numpy-1.21.0rc1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl
566c652f9cdb10f55777f030ce857824  numpy-1.21.0rc1-cp38-cp38-win32.whl
c09a49c8aef8a87267322343a1abaaf2  numpy-1.21.0rc1-cp38-cp38-win_amd64.whl
7755038d0c4a996c912c967b34a2aaff  numpy-1.21.0rc1-cp39-cp39-macosx_10_9_universal2.whl
a51746adf928b66b7ce6f51afe87fa5f  numpy-1.21.0rc1-cp39-cp39-macosx_10_9_x86_64.whl
3da1f90027f433e13cef63d12bdc6142  numpy-1.21.0rc1-cp39-cp39-macosx_11_0_arm64.whl
eff3767616a49ca7bec3f44476f07be8  numpy-1.21.0rc1-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.whl
c09d61a8afbc1ae1ffa5a4ba0f53616b  numpy-1.21.0rc1-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
7861468db5b918ee7188871daad34f1a  numpy-1.21.0rc1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
9d416859d0fe38b80d63ea1e368133d9  numpy-1.21.0rc1-cp39-cp39-win32.whl
d92e6574a0656f170d76f377f41f8dd3  numpy-1.21.0rc1-cp39-cp39-win_amd64.whl
8d8aa5cab5d2e6d94a4a09c33461776e  numpy-1.21.0rc1-pp37-pypy37_pp73-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
32a9675f747267c5e0bbe87a79ecc31b  numpy-1.21.0rc1.tar.gz


19e076e4d9b66fd63477e907ed2a4c6662bbcd5a74b2cf50a9b0753afb4ee167  numpy-1.21.0rc1-cp37-cp37m-macosx_10_9_x86_64.whl
8b92d27414779f568484c4a0aeddbff8e1fa9d9403cff122161fa25bc94e7f44  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.whl
a1c3737f659085eeaab83e016569368157d8d46d6a3be317c864dadd3c28fa42  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
35180d82f457f0857963a486c16bd472582f217827c839dcb3a3de298b532f11  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
438129e0d1dd03d235ae25c45b5621888d699935cf5b813d08a0bb2e7221c9d4  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.whl
63b3d66f5610c61d3d1b47687b99584fdf7734192344814d80f2670e0c7b05ef  numpy-1.21.0rc1-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.whl
4c6395cc3eefdd1c9ede1c84ad8e728edfc97ea506b04b9600d4cb61c7b80cb4  numpy-1.21.0rc1-cp37-cp37m-win32.whl
9abfe8ef4f8898d0448de735a3270de466553b61de8e6ddc31fc8770003fdfa4  numpy-1.21.0rc1-cp37-cp37m-win_amd64.whl
7ada705e3e9364f874c41fc370c23247f4c1466888dfd61ac5ec9277524928c2  numpy-1.21.0rc1-cp38-cp38-macosx_10_9_x86_64.whl
6ed13704d67934d458abeaacd96079bb8ae5f0ea000765777449e94288590097  numpy-1.21.0rc1-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.whl
305aff30d8976eccf14751a1095dac0e60e0c071f1fb82e6c53948fc5b6b346c  numpy-1.21.0rc1-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
a3a480ac4077c868124427456c6a64dcb7da12817bd3e770006980a4fd0d2526  numpy-1.21.0rc1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
80929da75a678433dcc8c79db94eb373408778d17fe9b49c4521501a5923a3e2  numpy-1.21.0rc1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl
234fc98750ada00204ebf3acd94baea213c6f9f0ff6b097d06952f734f67e58a  numpy-1.21.0rc1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl
da0797286c299c426e5b6cf03ca9e1dab0dace161b64d7a1879c4d15eb12ceba  numpy-1.21.0rc1-cp38-cp38-win32.whl
17f3ac57e19740f1c064c284ad361148be245fabbd6390bec3ffa814fb287fd6  numpy-1.21.0rc1-cp38-cp38-win_amd64.whl
57410c33aef7b3fd4ef2e5f09f1c084a21021055c74034748b8d2957a72dad01  numpy-1.21.0rc1-cp39-cp39-macosx_10_9_universal2.whl
4796c196faa5f5418ce9a8ee0e993c925755e505778e32442263422c4fe88013  numpy-1.21.0rc1-cp39-cp39-macosx_10_9_x86_64.whl
97faf00577c74a4f4b6304c1b7f6223fb0825d1a7cfaad5601cbeadd8282cd70  numpy-1.21.0rc1-cp39-cp39-macosx_11_0_arm64.whl
56d67935694d9270e0a9bcfd6b9169f81ef2c2e5e154acd57ac7afe2d48d7b29  numpy-1.21.0rc1-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.whl
b58c8c1ea4b80a5cbc756a11e446eec16088ebd9e080e71a64c458f6c07cb3c7  numpy-1.21.0rc1-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
723fff54844d9c1e01703ed2bc177f892fd89530b7671e8191a639d799cd75b7  numpy-1.21.0rc1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
dcc194082d94c45fe8a005861cdce6ec33b51c1dccf2a7e6044b33038b82f579  numpy-1.21.0rc1-cp39-cp39-win32.whl
ff442e4fe6e66019b2070352e0cd6e7dde994ff1267d45343b587ed621e4ec47  numpy-1.21.0rc1-cp39-cp39-win_amd64.whl
068cfc78963ce8b9dd2dc7ad1f2d5ebebc47e10103ea0166074e6bd31e78aeb8  numpy-1.21.0rc1-pp37-pypy37_pp73-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
3baf619f71612da80628e63def8d901832f76a9d396fde2613ea3d73277bc08d  numpy-1.21.0rc1.tar.gz

Don't miss a new numpy release

NewReleases is sending notifications on new releases.