NumPy 2.0 Release: Key Changes and Migration

As data science evolves, some changes to common libraries are necessary, and this time, the NumPy library is getting an update to version 2.0. This major update was released in June 2024, and it brings many new features and improvements to the popular Python library.

With such a huge leap in changes, there are bound to be some areas to take note of that might require you to adjust your existing code.

In this article, we'll share an overview of what NumPy 2.0 includes, the key changes made, and how you can migrate to NumPy 2.0.

Introduction to NumPy 2.0

Built upon years of feedback and technological advancements, NumPy 2.0 is an ambitious upgrade, unlike the many previous updates over the past few years.

In their release blog post, they introduced an updated API, improved scalar promotion rules, a new DType API and a new string DType, compatibility enhancements, and alignment of API standards. Through these efforts, users will notice significant improvements in performance and documentation.

However, with such a huge change to the library, this new release comes with some disruption. For example, the new API and ABI changes are backward-incompatible.

Major New Features

According to the release notes, NumPy 2.0 introduces significant changes, and here are the notable ones:

API and ABI changes

In this update, there have been several cleanup changes made to the API and ABI (Application Binary Interface).

With the new update, stated in NEP (NumPy Enhancement Proposal) 52, NumPy is breaking away from its usual stance of having backward compatibility to ensure a more streamlined API that's cleaner and simpler.

Here are some notable changes:

• Public and private API split: Using a module structure, the NumPy API for Python now has a clear split between public and private API.
• Namespace cleanup: Functions have been simplified to make learning NumPy easier. See the full removal list for more info.
• Deprecating niche functionality: Many of the non-recommended functions and aliases have been removed.
• New custom type: For the C API, a new public API for creating custom DType was released.

For the ABI changes, there will be a breakage with the new release. This will impact binaries of packages that use the NumPy C API.

Anyone who builds it against any previous NumPy 1.xx release will not work with NumPy 2.0. I'll share more on how things can be migrated according to their recommendation. You'll encounter an ImportError message, which indicates binary incompatibility.

New DType API and String DType

As proposed in NEP 41, this 2.0 update releases a new API for implementing user-defined custom data types using the StringDType data type. This new API includes native support for variable-length string data types, which NumPy users have long requested.

Scalar promotion rules

Initially proposed in NEP 50, the scalar promotion rules in NumPy have also been updated to prevent any user surprises. Previously, promotion often depended on data values of input arrays rather than only their DTypes, which can be a confusing behavior.

For the new promotion paths, see the image below:

Source: NumPy DType precision and promotion

Performance improvements

This new release also brings some performance improvements.

Here are some key areas that were improved:

• Faster sorting functions
• Improvements to linear algebra operations performance on macOS through macOS Accelerate

Windows compatibility

To better suit Windows users, the NumPy team has also fixed several compatibility issues with the new release.

For example, they have changed the default integer type on Windows to int64 rather than int32, to match the default behavior on other OS platforms.

Improved documentation and usability

More documentation was added to NumPy's module structure, and there were improvements to reference guide navigation. The building from source documentation was also entirely rewritten.

How to Migrate to NumPy 2.0

Updating to NumPy 2.0

First off, to get started with this new version of NumPy, you’ll need to upgrade it from your current version to the latest.

To do this, simply use the the upgrade option in this command:

pip install -U numpy

Alternatively, you can also use this:

pip install –upgrade numpy

This upgrade option updates the specified package(s) to the latest version, which in this case, is NumPy. After running the command, allow the system to install the package until you see the message “Successfully installed numpy-2.0.0”.

If you’d like to update to a specific version instead of the latest version, you can use this command instead:

pip install numpy==2.0.0

This ensures that the version you’re installing is the right one, which in this case is 2.0.0.

To do a second check, run this command:

pip list

This should list out all your installed packages/libraries and their respective versions. Check the output to see if the numpy libraries is updated to version 2.0.0. 

In the process of installing, you might also encounter some dependency messages popping up in red. This means that there are some potential problems with your code after updating to latest version. You can then look into the specific areas and libraries affected individually.

Upgrading to NumPy 2.0 is can be temporarily disruptive, so it's best to make sure things are all migrated well into your scripts and future pipelines.

For a full guide, please see the official NumPy 2.0 Migration Guide released by the developers.

Here are the key areas to take note when migrating:

Addressing NumPy data type promotion changes

For a full guide on how on the several change behaviors and expected data type changes, refer to this table in NEP 50.

The main backward compatibility issue is the precision of your scalars.

For example, when an operation like this is run:

np.float32(6) + 6.

This returns a float32 data type instead of a float64 data type, which makes backward compatibility difficult. To address this issue, here's what they recommend:

Cast data types explicitly: Use the int(), float(), or numpy_scalar.item() scalars to specify your data type explicitly.

Enable warnings to track down changes: Use warnings as a way to look for changes through error tracebacks.

Addressing namespace changes

With this 2.0 update, the numerous namespace removals can affect your code. The NumPy team suggests these steps:

1. Check for deprecated aliases and migration guidelines here.
2. Replace deprecated aliases with a backward-compatible alternative.
3. Check for private members that were removed in the 2.0 update.
4. Use the existing API if private members were used.

Addressing ABI breakage

If you're using a Python package that depends on NumPy’s C API, you'll have to address any breaks in ABI. The developers have released some NumPy 2.0-specific advice for such situations to address the incompatibility:

Ruff plugin to update Python code

To help you through your migration process, you can use the Ruff plugin with a dedicated Ruff rule, NPY201.

Ruff is available as ruff on PyPI. To install Ruff, enter this in the command line:

pip install ruff

For more details, see the full Ruff installation guide.

Make sure to specify the NP201 rule to your pyproject.toml:

[tool.ruff.lint]
select = ["NPY201"]

Alternatively, you can also specify the NPY201 rule using the command line:

$ ruff check path/to/code/ --select NPY201

Community Contributions

The NumPy 2.0 release is the culmination of the efforts of its community. Through the many NEPs suggested by the community, many of the long-awaited proposals have finally been implemented.

Enthusiastic developers, researchers, and enthusiasts have all played a pivotal role in this groundbreaking release, sharing their expertise, providing feedback, and submitting code enhancements that have significantly shaped NumPy 2.0.

Conclusion

NumPy 2.0 is a big step forward for the Python programming language, with its many new features and improvements in performance, compatibility, and usability. If you're experiencing any issues with migration or some form of error, it's best to approach the NumPy team directly.

I hope this article has been helpful in understanding the main changes in this exciting update to NumPy. For more in-depth reading, do read our NumPy Tutorial.

If you’re new to NumPy and would like to explore more, try out our Introduction to NumPy course or check out this NumPy live code along training.