Deprecations#

  • numpy.char.chararray is deprecated. Use an ndarray with a string or bytes dtype instead.

    (gh-30605)

  • The numpy.char.[as]array functions are deprecated. Use an numpy.[as]array with a string or bytes dtype instead.

    (gh-30802)

Setting the shape attribute is deprecated#

Setting the shape attribute is now deprecated since mutating an array is unsafe if an array is shared, especially by multiple threads. As an alternative, you can create a new view via np.reshape or np.ndarray.reshape. For example: x = np.arange(15); x = np.reshape(x, (3, 5)). To ensure no copy is made from the data, one can use np.reshape(..., copy=False).

Directly setting the shape on an array is discouraged, but for cases where it is difficult to work around, e.g., in __array_finalize__ possible with the private method np.ndarray._set_shape.

(gh-29536)

Resizing a Numpy array inplace is deprecated#

Resizing a Numpy array inplace is deprecated since mutating an array is unsafe if an array is shared, especially by multiple threads. As an alternative, you can create a resized array via np.resize.

(gh-30181)

numpy.fix is deprecated#

numpy.fix is deprecated. Use numpy.trunc instead, which is faster and follows the Array API standard. Both functions provide identical functionality: rounding array elements towards zero.

(gh-30644)

numpy.ma.round_ is deprecated#

numpy.ma.round_ is deprecated. numpy.ma.round can be used as a replacement.

(gh-30738)

typename is deprecated#

numpy.typename is deprecated because the names returned by it were outdated and inconsistent. numpy.dtype.name can be used as a replacement.

(gh-30774)

Expired deprecations#

  • numpy.distutils has been removed

    (gh-30340)

  • Passing None as dtype to np.finfo will now raise a TypeError (deprecated since 1.25)

    (gh-30460)

  • numpy.cross no longer supports 2-dimensional vectors (deprecated since 2.0)

    (gh-30461)

  • numpy._core.numerictypes.maximum_sctype has been removed (deprecated since 2.0)

    (gh-30462)

  • numpy.row_stack has been removed in favor of numpy.vstack (deprecated since 2.0).

  • get_array_wrap has been removed (deprecated since 2.0).

    (gh-30463)

  • recfromtxt and recfromcsv have been removed from numpy.lib._npyio in favor of numpy.genfromtxt (deprecated since 2.0).

    (gh-30467)

  • The numpy.chararray re-export of numpy.char.chararray has been removed (deprecated since 2.0).

    (gh-30604)

  • bincount now raises a TypeError for non-integer inputs (deprecated since 2.1).

    (gh-30610)

  • The numpy.lib.math alias for the standard library math module has been removed (deprecated since 1.25).

    (gh-30612)

  • Data type alias 'a' was removed in favor of 'S' (deprecated since 2.0).

    (gh-30613)

  • _add_newdoc_ufunc(ufunc, newdoc) has been removed in favor of ufunc.__doc__ = newdoc (deprecated in 2.2)

    (gh-30614)

Compatibility notes#

linalg.eig and linalg.eigvals now always return complex arrays#

Previously, the return values depended on whether the eigenvalues happen to lie on the real line (which, for a general, non-symmetric matrix, is not guaranteed).

The change makes consistent what was a value-dependent result. To retain the previous behavior, do:

w = eigvals(a)
if np.any(w.imag == 0):  # this is what NumPy used to do
    w = w.real

If your matrix is symmetrix/hermitian, use eigh and eigvalsh instead of eig and eigvals. These are guaranteed to return real values. A common case is covariance matrices, which are symmetric and positive definite by construction.

(gh-30411)

MSVC support#

NumPy now requires minimum MSVC 19.35 toolchain version on Windows platforms. This corresponds to Visual Studio 2022 version 17.5 Preview 2 or newer.

(gh-30489)

Cython support#

NumPy’s Cython headers (accessed via cimport numpy) now require Cython 3.0 or newer to build. If you try to compile a project that depends on NumPy’s Cython headers using Cython 0.29 or older, you will see a message like this:

Error compiling Cython file:
------------------------------------------------------------
...
# versions.
#
# See __init__.cython-30.pxd for the real Cython header
#

DEF err = int('Build aborted: the NumPy Cython headers require Cython 3.0.0 or newer.')
  ------------------------------------------------------------

  /path/to/site-packages/numpy/__init__.pxd:11:13: Error in compile-time expression: ValueError: invalid literal for int() with base 10: 'Build aborted: the NumPy Cython headers require Cython 3.0.0 or newer.'

Note that the invalid integer is not a bug in NumPy - we are intentionally generating this error to avoid triggering a more obscure error later in the build when an older Cython version tries to use a Cython feature that was not available in the old Cython version.

(gh-30770)

New Features#

Pixi package definitions#

Pixi package definitions have been added for different kinds of from-source builds of NumPy. These can be used in downstream Pixi workspaces via the pixi-build feature.

Definitions for both default and AddressSanitizer-instrumented (asan) builds are available in the source code under the pixi-packages/ directory.

linux-64 and osx-arm64 platforms are supported.

(gh-30381)

numpy.ndarray now supports structural pattern matching#

numpy.ndarray and its subclasses now have the Py_TPFLAGS_SEQUENCE flag set, enabling structural pattern matching (PEP 634) with match/case statements. This also enables Cython to optimize integer indexing operations. See Structural pattern matching for details.

(gh-30653)

Improvements#

For f2py, the behaviour of intent(inplace) has improved. Previously, if an input array did not have the right dtype or order, the input array was modified in-place, changing its dtype and replacing its data by a corrected copy. Now, instead, the corrected copy is kept a separate array, which, after being passed and presumably modified by the fortran routine, is copied back to the input routine. The above means one no longer has the risk that pre-existing views or slices of the input array start pointing to unallocated memory (at the price of increased overhead for the write-back copy at the end of the call).

A potential problem would be that one might get very different results if one, e.g., previously passed in an integer array where a double array was expected: the writeback to integer would likely give wrong results. To avoid such situations, intent(inplace) will now only allow arrays that have equivalent type to that used in the fortran routine, i.e., dtype.kind is the same. For instance, a routine expecting double would be able to receive float, but would raise on integer input.

(gh-29929)

Performance improvements and changes#

Improved performance of numpy.searchsorted#

The C++ binary search implementation used by numpy.searchsorted now has a much better performance when searching for multiple keys. The new implementation batches binary search steps across all keys to leverage cache locality and out-of-order execution. Benchmarks show the new implementation can be up to 20 times faster for hundreds of thousands keys while single-key performance remains comparable to previous versions.

(gh-30517)

Typing improvements and changes#

numpy.linalg typing improvements and preliminary shape-typing support#

Input and output dtypes for numpy.linalg functions are now more precise. Several of these functions also gain preliminary shape-typing support while remaining backward compatible. For example, the return type of numpy.linalg.matmul now depends on the shape-type of its inputs, or fall back to the backward-compatible return type if the shape-types are unknown at type-checking time. Because of limitations in Python’s type system and current type-checkers, shape-typing cannot cover every situation and is often only implemented for the most common lower-rank cases.

(gh-30480)

numpy.ma typing annotations#

The numpy.ma module is now fully covered by typing annotations. This includes annotations for masked arrays, masks, and various functions and methods. With this, NumPy has achieved 100% typing coverage across all its submodules.

(gh-30566)

Changes#

numpy.ctypeslib.as_ctypes now does not support scalar types#

The function numpy.ctypeslib.as_ctypes has been updated to only accept numpy.ndarray. Passing a scalar type (e.g., numpy.int32(5)) will now raise a TypeError. This change was made to avoid the issue gh-30354 and to enforce the readonly nature of scalar types in NumPy. The previous behavior relied on undocumented implicit temporary arrays and was not well-defined. Users who need to convert scalar types to ctypes should first convert them to an array (e.g., numpy.asarray) before passing them to numpy.ctypeslib.as_ctypes.

__array_interface__ changes on scalars#

Scalars now export the __array_interface__ directly rather than including an array copy as a __ref entry. This means that scalars are now exported as read-only while they previously exported as writeable. The path via __ref was undocumented and not consistently used even within NumPy itself.

(gh-30538)

meshgrid now always returns a tuple#

np.meshgrid previously used to return a list when sparse was true and copy was false. Now, it always returns a tuple regardless of the arguments.

(gh-30707)