NumPy 2.0 migration guide#
This document contains a set of instructions on how to update your code to work with Numpy 2.0.
Windows default integer#
The default integer used by NumPy is now 64bit on all 64bit systems (and
32bit on 32bit system). For historic reasons related to Python 2 it was
previously equivalent to the C long
type.
The default integer is now equivalent to np.intp
.
Most end-users should not be affected by this change. Some operations will
use more memory, but some operations may actually become faster.
If you experience issues due to calling a library written in a compiled
language it may help to explicitly cast to a long
, for example with:
arr = arr.astype("long", copy=False)
.
Libraries interfacing with compiled code that are written in C, Cython, or
a similar language may require updating to accomodate user input if they
are using the long
or equivalent type on the C-side.
In this case, you may wish to use intp
and cast user input or support
both long
and intp
(to better support NumPy 1.x as well).
When creating a new integer array in C or Cython, the new NPY_DEFAULT_INT
macro will evaluate to either NPY_LONG
or NPY_INTP
depending on the
NumPy version.
Note that the NumPy random API is not affected by this change.
C-API Changes#
Some definitions where removed or replaced due to being outdated or
unmaintaibale. Some new API definition will evaluate differently at
runtime between NumPy 2.0 and NumPy 1.x.
Some are defined in numpy/_core/include/numpy/npy_2_compat.h
(for example NPY_DEFAULT_INT
) which can be vendored in full or part
to have the definitions available when compiling against NumPy 1.x.
If necessary, PyArray_RUNTIME_VERSION >= NPY_2_0_API_VERSION
can be
used to explicitly implement different behavior on NumPy 1.x and 2.0.
(The compat header defines it in a way compatible with such use.)
Please let us know if you require additional workarounds here.
Increased maximum number of dimensions#
The maximum number of dimensions (and arguments) was increased to 64, this
affects the NPY_MAXDIMS
and NPY_MAXARGS
macros.
It may be good to review their use, and we generally encourage you to
not use these macros (especially NPY_MAXARGS
), so that a future version of
NumPy can remove this limitation on the number of dimensions.
NPY_MAXDIMS
was also used to signal axis=None
in the C-API, including
the PyArray_AxisConverter
.
The latter will return -2147483648
as an axis (the smallest integer value).
Other functions may error with
AxisError: axis 64 is out of bounds for array of dimension
in which
case you need to pass NPY_RAVEL_AXIS
instead of NPY_MAXDIMS
.
NPY_RAVEL_AXIS
is defined in the npy_2_compat.h
header and runtime
dependent (mapping to 32 on NumPy 1.x and -2147483648
on NumPy 2.x).
Namespace changes#
In NumPy 2.0 certain functions, modules, and constants were moved or removed to make the NumPy namespace more userfriendly by removing unnecessary or outdated functionality and clarifying which parts of NumPy are considered private. Please see the tables below for guidance on migration. For most changes this means replacing it with a backwards compatible alternative.
Please refer to NEP 52 for more details.
Main namespace#
About 100 members of the main np
namespace has been deprecated, removed, or
moved to a new place. It was done to reduce clutter and establish only one way to
access a given attribute. The table below shows members that have been removed:
removed member |
migration guideline |
---|---|
add_docstring |
It’s still available as |
add_newdoc |
It’s still available as |
add_newdoc_ufunc |
It’s an internal function and doesn’t have a replacement. |
asfarray |
Use |
byte_bounds |
Now it’s available under |
cast |
Use |
cfloat |
Use |
clongfloat |
Use |
compat |
There’s no replacement, as Python 2 is no longer supported. |
complex_ |
Use |
DataSource |
It’s still available as |
deprecate |
Emit |
deprecate_with_doc |
Emit |
disp |
Use your own printing function instead. |
fastCopyAndTranspose |
Use |
find_common_type |
Use |
get_array_wrap |
|
float_ |
Use |
geterrobj |
Use the np.errstate context manager instead. |
Inf |
Use |
Infinity |
Use |
infty |
Use |
issctype |
Use |
issubclass_ |
Use |
issubsctype |
Use |
mat |
Use |
maximum_sctype |
Use a specific dtype instead. You should avoid relying on any implicit mechanism and select the largest dtype of a kind explicitly in the code. |
NaN |
Use |
nbytes |
Use |
NINF |
Use |
NZERO |
Use |
longcomplex |
Use |
longfloat |
Use |
lookfor |
Search NumPy’s documentation directly. |
obj2sctype |
Use |
PINF |
Use |
PZERO |
Use |
recfromcsv |
Use |
recfromtxt |
Use |
round_ |
Use |
safe_eval |
Use |
sctype2char |
Use |
sctypes |
Access dtypes explicitly instead. |
seterrobj |
Use the np.errstate context manager instead. |
set_numeric_ops |
For the general case, use |
set_string_function |
Use |
singlecomplex |
Use |
string_ |
Use |
source |
Use |
tracemalloc_domain |
It’s now available from |
unicode_ |
Use |
who |
Use an IDE variable explorer or |
If the table doesn’t contain an item that you were using but was removed in 2.0
,
then it means it was a private member. You should either use the existing API or,
in case it’s infeasible, reach out to us with a request to restore the removed entry.
The next table presents deprecated members, which will be removed in a release after 2.0
:
deprecated member |
migration guideline |
---|---|
in1d |
Use |
row_stack |
Use |
trapz |
Use |
Finally, a set of internal enums has been removed. As they weren’t used in downstream libraries we don’t provide any information on how to replace them:
[FLOATING_POINT_SUPPORT
, FPE_DIVIDEBYZERO
, FPE_INVALID
, FPE_OVERFLOW
,
FPE_UNDERFLOW
, UFUNC_BUFSIZE_DEFAULT
, UFUNC_PYVALS_NAME
, CLIP
, WRAP
,
RAISE
, BUFSIZE
, ALLOW_THREADS
, MAXDIMS
, MAY_SHARE_EXACT
,
MAY_SHARE_BOUNDS
]
Lib namespace#
Most of the functions available within np.lib
are also present in the main
namespace, which is their primary location. To make it unambiguous how to access each
public function, np.lib
is now empty and contains only a handful of specialized submodules,
classes and functions:
array_utils
,format
,introspect
,mixins
,npyio
andstride_tricks
submodules,Arrayterator
andNumpyVersion
classes,add_docstring
andadd_newdoc
functions,tracemalloc_domain
constant.
If you get an AttributeError
when accessing an attribute from np.lib
you should
try accessing it from the main np
namespace then. If an item is also missing from
the main namespace, then you’re using a private member. You should either use the existing
API or, in case it’s infeasible, reach out to us with a request to restore the removed entry.
Core namespace#
np.core
namespace is now officially private and has been renamed to np._core
.
The user should never fetch members from the _core
directly - instead the main
namespace should be used to access the attribute in question. The layout of the _core
module might change in the future without notice, contrary to public modules which adhere
to the deprecation period policy. If an item is also missing from the main namespace,
then you should either use the existing API or, in case it’s infeasible, reach out to us
with a request to restore the removed entry.
ndarray and scalar namespace#
A few methods from np.ndarray
and np.generic
scalar classes have been removed.
The table below provides replacements for the removed members:
expired member |
migration guideline |
---|---|
newbyteorder |
Use |
ptp |
Use |
setitem |
Use |
… |
… |
Note about pickled files#
NumPy 2.0 is designed to load pickle files created with NumPy 1.26, and vice versa. For versions 1.25 and earlier loading NumPy 2.0 pickle file will throw an exception.