A NumPy computation produces different answers after a library upgrade. How would you debug it?

Why

First establish whether the change is real or within floating-point noise. Differences in the last few digits can come from a new summation order or a different BLAS build and are often acceptable. A change in the third significant figure, or a count that moves, is a defect to explain.

Rebuild the old environment from a pinned lock file so the two runs differ only by the upgrade. Then save intermediate arrays from both and find the first stage where they diverge, recording each array's dtype. NumPy 2.0 adopted NEP 50, which changed type promotion so that Python scalars are weak and no longer upcast a NumPy value. np.float32(3) + 3.0 now returns float32 instead of float64, and np.uint8(100) + 200 now overflows to 44 with a warning instead of returning 300.

A pipeline that kept image intensities as uint8 and added an offset can therefore produce quietly different results. NumPy 2 also made the default integer 64-bit on 64-bit Windows. The migration guide suggests explicit casts, and the Ruff rule NPY201 flags many removed or renamed functions.

If the stages agree but final results differ, look at downstream libraries compiled against the old NumPy. Afterward, add a regression test with tolerances on a small reference input.