github numpy/numpy v1.21.0

latest releases: v1.23.0rc1, v1.24.0.dev0, v1.22.4...
11 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,
  • universal2 wheels for Python 3.8 and Python 3.9 on Mac,
  • improved documentation,
  • improved annotations,
  • 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.

⚠️ Warning: there are unresolved problems compiling NumPy 1.21.0 with gcc-11.1 .

  • Optimization level -O3 results in many wrong warnings when running the tests.
  • On some hardware NumPy will hang in an infinite loop.

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 for more details.


Expired deprecations

  • The shape argument 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.



The .dtype attribute must return a dtype

A DeprecationWarning is now given if the .dtype attribute of an
object passed into np.dtype or as a dtype=obj argument is not a
dtype. NumPy will stop attempting to recursively coerce the result of


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
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)


Expired deprecations

  • The shape argument 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.


Remove deprecated PolyBase and unused PolyError and PolyDomainError

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

Furthermore, the unused PolyError and PolyDomainError exceptions are
removed from the numpy.polynomial.


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>
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 file]

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.

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.




e4b31fd5cb97e50238b3dbb3487b2cb7  numpy-1.21.0-cp37-cp37m-macosx_10_9_x86_64.whl
111e09f3fddd8e14540cf56493dd786a  numpy-1.21.0-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.whl
e2fc116043d1b91c627f3c8884151f33  numpy-1.21.0-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
82e267da77628b96cdf8832e475f6ef3  numpy-1.21.0-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
baa416fe77b840a19556f5d808eb3165  numpy-1.21.0-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.whl
aba24836f51bb0a855434c41de122e3d  numpy-1.21.0-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.whl
aa9f94fa6eabfa193902676825934196  numpy-1.21.0-cp37-cp37m-win32.whl
6d771c7670b95adb62627e383c883804  numpy-1.21.0-cp37-cp37m-win_amd64.whl
e6d77cae6054b738603415faf9cb4358  numpy-1.21.0-cp38-cp38-macosx_10_9_universal2.whl
9589cfe5a22f54956101b7131be5cabd  numpy-1.21.0-cp38-cp38-macosx_10_9_x86_64.whl
5faa22dffa53cfe7d1d40d48aa817670  numpy-1.21.0-cp38-cp38-macosx_11_0_arm64.whl
b81545a2924a201817d433c3bad0bc7d  numpy-1.21.0-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.whl
3e60589e3325a3583880bf6998cfaca6  numpy-1.21.0-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
baf409eb08b7462899d45c42a7c1d854  numpy-1.21.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
4f311de7973503dde6ad3915f158fd63  numpy-1.21.0-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl
1a79926ad8d3dda573f5c2d8d06e0e38  numpy-1.21.0-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl
0b39eb396a1d5983f6eb2075a867a1a6  numpy-1.21.0-cp38-cp38-win32.whl
5c8c3e94f5a55123b1a0d3a4df14b505  numpy-1.21.0-cp38-cp38-win_amd64.whl
c6e9fa30e82e3ca1551d2f048d4a1dc4  numpy-1.21.0-cp39-cp39-macosx_10_9_universal2.whl
96d7d3a438296bfc68b819b3624936a5  numpy-1.21.0-cp39-cp39-macosx_10_9_x86_64.whl
31cf2152b4151912be9d165633a7d8eb  numpy-1.21.0-cp39-cp39-macosx_11_0_arm64.whl
e49cd2db6ec712b8b1d516154b5a034a  numpy-1.21.0-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.whl
c10e13fef152ed1c64151c8b6f6d0799  numpy-1.21.0-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
a627acdfcd302807cf8592d5bd958d35  numpy-1.21.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
e2287cd16300b363d376b661646fded9  numpy-1.21.0-cp39-cp39-win32.whl
29d1bf596981d930bb1c95c944b4b3d8  numpy-1.21.0-cp39-cp39-win_amd64.whl
42d05fcbab6137a404be36f27fc254f0  numpy-1.21.0-pp37-pypy37_pp73-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
003e34bd2cba06e7fe299a864964ea24  numpy-1.21.0.tar.gz


d5caa946a9f55511e76446e170bdad1d12d6b54e17a2afe7b189112ed4412bb8  numpy-1.21.0-cp37-cp37m-macosx_10_9_x86_64.whl
ac4fd578322842dbda8d968e3962e9f22e862b6ec6e3378e7415625915e2da4d  numpy-1.21.0-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.whl
598fe100b2948465cf3ed64b1a326424b5e4be2670552066e17dfaa67246011d  numpy-1.21.0-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
7c55407f739f0bfcec67d0df49103f9333edc870061358ac8a8c9e37ea02fcd2  numpy-1.21.0-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
75579acbadbf74e3afd1153da6177f846212ea2a0cc77de53523ae02c9256513  numpy-1.21.0-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.whl
cc367c86eb87e5b7c9592935620f22d13b090c609f1b27e49600cd033b529f54  numpy-1.21.0-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.whl
d89b0dc7f005090e32bb4f9bf796e1dcca6b52243caf1803fdd2b748d8561f63  numpy-1.21.0-cp37-cp37m-win32.whl
eda2829af498946c59d8585a9fd74da3f810866e05f8df03a86f70079c7531dd  numpy-1.21.0-cp37-cp37m-win_amd64.whl
1a784e8ff7ea2a32e393cc53eb0003eca1597c7ca628227e34ce34eb11645a0e  numpy-1.21.0-cp38-cp38-macosx_10_9_universal2.whl
bba474a87496d96e61461f7306fba2ebba127bed7836212c360f144d1e72ac54  numpy-1.21.0-cp38-cp38-macosx_10_9_x86_64.whl
fd0a359c1c17f00cb37de2969984a74320970e0ceef4808c32e00773b06649d9  numpy-1.21.0-cp38-cp38-macosx_11_0_arm64.whl
e4d5a86a5257843a18fb1220c5f1c199532bc5d24e849ed4b0289fb59fbd4d8f  numpy-1.21.0-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.whl
620732f42259eb2c4642761bd324462a01cdd13dd111740ce3d344992dd8492f  numpy-1.21.0-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
b9205711e5440954f861ceeea8f1b415d7dd15214add2e878b4d1cf2bcb1a914  numpy-1.21.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
ad09f55cc95ed8d80d8ab2052f78cc21cb231764de73e229140d81ff49d8145e  numpy-1.21.0-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl
a1f2fb2da242568af0271455b89aee0f71e4e032086ee2b4c5098945d0e11cf6  numpy-1.21.0-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl
e58ddb53a7b4959932f5582ac455ff90dcb05fac3f8dcc8079498d43afbbde6c  numpy-1.21.0-cp38-cp38-win32.whl
d2910d0a075caed95de1a605df00ee03b599de5419d0b95d55342e9a33ad1fb3  numpy-1.21.0-cp38-cp38-win_amd64.whl
a290989cd671cd0605e9c91a70e6df660f73ae87484218e8285c6522d29f6e38  numpy-1.21.0-cp39-cp39-macosx_10_9_universal2.whl
3537b967b350ad17633b35c2f4b1a1bbd258c018910b518c30b48c8e41272717  numpy-1.21.0-cp39-cp39-macosx_10_9_x86_64.whl
ccc6c650f8700ce1e3a77668bb7c43e45c20ac06ae00d22bdf6760b38958c883  numpy-1.21.0-cp39-cp39-macosx_11_0_arm64.whl
709884863def34d72b183d074d8ba5cfe042bc3ff8898f1ffad0209161caaa99  numpy-1.21.0-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.whl
bebab3eaf0641bba26039fb0b2c5bf9b99407924b53b1ea86e03c32c64ef5aef  numpy-1.21.0-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
cf680682ad0a3bef56dae200dbcbac2d57294a73e5b0f9864955e7dd7c2c2491  numpy-1.21.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
d95d16204cd51ff1a1c8d5f9958ce90ae190be81d348b514f9be39f878b8044a  numpy-1.21.0-cp39-cp39-win32.whl
2ba579dde0563f47021dcd652253103d6fd66165b18011dce1a0609215b2791e  numpy-1.21.0-cp39-cp39-win_amd64.whl
3c40e6b860220ed862e8097b8f81c9af6d7405b723f4a7af24a267b46f90e461  numpy-1.21.0-pp37-pypy37_pp73-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
b662c841b29848c04d9134f31dbaa7d4c8e673f45bb3a5f28d02f49c424d558a  numpy-1.21.0.tar.gz

Don't miss a new numpy release

NewReleases is sending notifications on new releases.