Change8

Migrating to NumPy v2.5.0rc1

Version v2.5.0rc1 introduces 14 breaking changes. This guide details how to update your code.

Released: 6/2/2026

14
Breaking Changes
13
Migration Steps
36
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

numpy.char.chararraynumpy.takenumpy.compressnumpy.char.[as]arraynumpy.dtype.__set__numpy.ndarray.shape.__set__numpy.timedelta64numpy.resizenumpy.fixnumpy.truncnumpy.ma.round_numpy.ma.roundnumpy.typenamenumpy.dtype.namenumpy.triu_indicesnumpy.tril_indicesnumpy.trinumpy.tril_indices_fromnumpy.triu_indices_fromnumpy.ndarray.__array_finalize__numpy.ndarray._set_dtypenumpy.distutilsnumpy.finfonumpy.crossnumpy._core.numerictypes.maximum_sctypenumpy.row_stacknumpy.vstackget_array_wrapnumpy.lib._npyio.recfromtxtnumpy.lib._npyio.recfromcsvnumpy.genfromtxtnumpy.chararraynumpy.bincountnumpy.lib.mathnumpy.linalg.eignumpy.linalg.eigvals

Breaking Changes

Issue #1

Support for Python 3.11 has been dropped. Users must upgrade to Python 3.12 or newer.

Issue #2

The entire `numpy.distutils` module has been removed. Users should migrate build systems away from distutils.

Issue #3

Passing `None` as dtype to `np.finfo` now raises a `TypeError` (previously deprecated since 1.25).

Issue #4

`numpy.cross` no longer supports 2-dimensional vectors. Ensure inputs are 1D or 3D vectors.

Issue #5

`numpy._core.numerictypes.maximum_sctype` has been removed.

Issue #6

`numpy.row_stack` has been removed; use `numpy.vstack` instead.

Issue #7

`get_array_wrap` has been removed.

Issue #8

`recfromtxt` and `recfromcsv` have been removed from `numpy.lib._npyio`; use `numpy.genfromtxt` instead.

Issue #9

The re-export of `numpy.char.chararray` from `numpy.chararray` has been removed.

Issue #10

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

Issue #11

The alias `numpy.lib.math` for the standard library `math` module has been removed.

Issue #12

Data type alias `'a'` has been removed; use `'S'` instead.

Issue #13

`_add_newdoc_ufunc(ufunc, newdoc)` has been removed; use `ufunc.__doc__ = newdoc` directly.

Issue #14

`linalg.eig` and `linalg.eigvals` now always return complex arrays, even if eigenvalues are real. To retain previous behavior when eigenvalues are real, check `np.any(w.imag == 0)` and handle accordingly.

Migration Steps

  1. 1
    If you were using `numpy.distutils`, migrate your build system away from it.
  2. 2
    Replace usage of `numpy.char.chararray` with an `ndarray` having a string or bytes dtype.
  3. 3
    Replace usage of `numpy.char.[as]array` functions with `numpy.[as]array` specifying a string or bytes dtype.
  4. 4
    Instead of setting `arr.dtype = new_dtype`, use `arr.view(dtype=new_dtype)` to create a view with a new dtype.
  5. 5
    Instead of setting `arr.shape = new_shape`, use `np.reshape(arr, new_shape)` or `arr.reshape(new_shape)`.
  6. 6
    When constructing `numpy.timedelta64`, specify an explicit unit like `'s'` or `'D'` instead of using the generic unit.
  7. 7
    Replace in-place resizing of arrays with `np.resize(arr, new_shape)`.
  8. 8
    Replace calls to `numpy.fix` with `numpy.trunc`.
  9. 9
    Replace calls to `numpy.ma.round_` with `numpy.ma.round`.
  10. 10
    Replace calls to `numpy.typename` with `numpy.dtype.name`.
  11. 11
    Ensure that inputs to `numpy.triu_indices` and `numpy.tril_indices` are integers. Ensure `M`, `k`, and `N` parameters for `numpy.tri` are integers, and `k` for `numpy.tril_indices_from` and `numpy.triu_indices_from` are integers.
  12. 12
    If you have custom dtypes or logic in `__array_finalize__` affected by dtype setting changes, review the deprecation note regarding setting `_set_dtype = None` or defining `_set_dtype`.
  13. 13
    If you relied on `linalg.eig` or `linalg.eigvals` returning real arrays when eigenvalues were real, you must now explicitly check if the imaginary part is zero and handle the result accordingly.

Release Summary

NumPy 2.5.0 is a transitional release that removes distutils support, expires many older deprecations, and introduces new deprecations for unsafe array mutation methods. It also adds support for descending sorts and improves free threading.

Need More Details?

View the full release notes and all changes for NumPy v2.5.0rc1.

View Full Changelog