●Change8

Migrating to NumPy v2.5.0

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

Released: 6/21/2026

13
Breaking Changes
14
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.dtypenumpy.shapenumpy.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.chararraybincountnumpy.lib.mathnumpy.linalg.eignumpy.linalg.eigvals

Breaking Changes

●Issue #1

The `numpy.distutils` module has been completely removed. Users relying on it must migrate to standard Python packaging tools.

●Issue #2

Passing `None` as dtype to `np.finfo` now raises a `TypeError` instead of being accepted.

●Issue #3

`numpy.cross` no longer supports 2-dimensional vectors.

●Issue #4

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

●Issue #5

`get_array_wrap` has been removed.

●Issue #6

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

●Issue #7

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

●Issue #8

`bincount` now raises a `TypeError` for non-integer inputs.

●Issue #9

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

●Issue #10

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

●Issue #11

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

●Issue #12

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

●Issue #13

`linalg.eig` and `linalg.eigvals` now always return complex arrays, even if eigenvalues are real. To retain previous behavior for non-symmetric matrices, explicitly check if the imaginary part is zero or use logic to cast if necessary.

Migration Steps

  1. 1
    If using `numpy.distutils`, migrate to standard Python packaging tools.
  2. 2
    When using `np.take` or `np.compress`, ensure the output array specified by `out=` is compatible with the result dtype according to the same-kind rule, or handle the resulting `DeprecationWarning`.
  3. 3
    Replace usage of `numpy.char.chararray` with an `ndarray` having a string or bytes dtype.
  4. 4
    Replace usage of `numpy.char.[as]array` functions with `numpy.[as]array` using string or bytes dtype.
  5. 5
    Instead of setting `arr.dtype`, create a view with a new dtype using `array.view(dtype=new_dtype)`.
  6. 6
    Instead of setting `arr.shape`, use `np.reshape(arr, new_shape)` or `arr.reshape(new_shape)`.
  7. 7
    When constructing `numpy.timedelta64`, specify an explicit unit like `'s'` or `'D'` instead of using the generic unit.
  8. 8
    Replace in-place array resizing with `np.resize(arr, new_size)`.
  9. 9
    Replace `numpy.fix` with `numpy.trunc`.
  10. 10
    Replace `numpy.ma.round_` with `numpy.ma.round`.
  11. 11
    Replace `numpy.typename` with `numpy.dtype.name`.
  12. 12
    Ensure 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 index functions are integers.
  13. 13
    If you have a subclass implementing custom dtype logic in `__array_finalize__` or a `dtype` property, set `_set_dtype = None` in the subclass definition, or define `_set_dtype` as a function calling `ndarray._set_dtype()` to manage view creation correctly.
  14. 14
    If using `linalg.eig` or `linalg.eigvals` on non-symmetric matrices and expecting real results, explicitly check if the imaginary part is zero or handle the complex output.

Release Summary

NumPy 2.5.0 is a transitional release that removes distutils support, expires many old deprecations, and introduces new deprecations related to array mutation and type handling. 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.0.

View Full Changelog