NumPy 2.0 发布：关键变更与迁移指南

随着数据科学的发展，一些常用库也需要做出调整。这一次， NumPy 库更新至 2.0 版本。这一重大版本已于 2024 年 6 月发布，为这款广受欢迎的 Python 库带来了诸多新功能和改进。

如此大幅度的变更，难免会有需要注意的地方，可能需要您调整现有代码。

本文将概述 NumPy 2.0 的内容、关键变化，以及如何迁移至 NumPy 2.0。

NumPy 2.0 简介

基于多年的用户反馈与技术进步，NumPy 2.0 是一次雄心勃勃的升级，与过去几年的多次更新有所不同。

在其 发布博文中，他们介绍了更新的 API、改进的标量提升规则、全新的 DType API 与字符串 DType、兼容性增强，以及 API 标准的统一。通过这些努力，用户将明显感受到性能与文档的提升。

不过，如此大规模的变更也会带来一些扰动。例如，新的 API 和 ABI 变更与旧版本并不兼容。

主要新特性

按照发布说明，NumPy 2.0 带来了重要变更，以下是值得关注的内容：

API 和 ABI 变更

在此次更新中，针对 API 与 ABI（应用二进制接口）进行了多项 清理性变更。

根据 NEP（NumPy 增强提案）52 的说明，为了让 API 更精简与清晰，NumPy 在此次更新中打破了以往对向后兼容性的坚持。

以下是一些显著变更：

• 公共与私有 API 的拆分：通过模块结构，Python 端的 NumPy API 现在清晰地区分了公共与私有 API。
• 命名空间清理：对函数进行了简化，便于学习 NumPy。参见 完整移除列表 以了解更多信息。
• 弃用小众功能：多项不推荐使用的函数与别名被移除。
• 新的自定义类型：针对 C API，发布了用于创建自定义 DType 的公共 API。

关于 ABI 变更，新版本会引入不兼容。这将影响使用 NumPy C API 的包的二进制文件。

凡是基于任何 1.xx 版本 NumPy 构建的内容都无法与 NumPy 2.0 一起工作。稍后将根据官方建议介绍如何迁移。您会遇到 ImportError，其指示为二进制不兼容。

新的 DType API 与字符串 DType

根据 NEP 41 的提案，2.0 更新发布了一套用于通过StringDType 数据类型实现用户自定义数据类型的新 API。该 API 原生支持可变长度字符串数据类型，这是 NumPy 用户长期以来的诉求。

标量提升规则

最初在 NEP 50 中提出，NumPy 的标量提升规则也已更新，以避免给用户带来意外。此前，类型提升常常依赖于输入数组的数据值而非仅其 DType，这种行为容易令人困惑。

新的提升路径见下图：

来源：NumPy DType 精度与提升

性能改进

此次发布还带来了一些性能提升。

以下是改进的重点领域：

• 更快的排序函数
• 通过 macOS Accelerate 提升在 macOS 上的线性代数运算性能

Windows 兼容性

为更好地服务 Windows 用户，NumPy 团队在新版本中修复了多项兼容性问题。

例如，他们将 Windows 上的默认整数类型从 int32 改为 int64，以与其他操作系统平台的默认行为保持一致。

改进的文档与可用性

为 NumPy 的模块结构新增了更多文档，并改进了参考指南的导航。从源码构建的文档也被完全重写。

如何迁移至 NumPy 2.0

升级到 NumPy 2.0

首先，要开始使用这一新版 NumPy，您需要将当前版本升级到最新版本。

为此，只需在以下命令中使用升级选项：

pip install -U numpy

或者，您也可以这样做：

pip install –upgrade numpy

该升级选项会将指定包更新到最新版本，在此处即为 NumPy。运行命令后，等待系统安装，直到出现“Successfully installed numpy-2.0.0”的提示信息。

如果您希望更新到特定版本而非最新版本，可以使用以下命令：

pip install numpy==2.0.0

这可确保安装的版本正确，此处为 2.0.0。

要进行二次确认，请运行以下命令：

pip list

这将列出您已安装的所有包/库及其版本。检查输出，确认 numpy 库是否已更新至 2.0.0 版本。

在安装过程中，您也可能会看到一些以红色显示的依赖提示消息。这意味着在更新到最新版本后，您的代码可能存在潜在问题。您可以分别查看受影响的具体区域和库。

升级到 NumPy 2.0 可能会带来短暂的扰动，因此最好确保您的脚本和后续流水线都已顺利完成迁移。

完整指南请参阅开发者发布的官方 NumPy 2.0 迁移指南。

以下是迁移时需要注意的重点：

应对 NumPy 数据类型提升的变更

关于多项行为变更与预期数据类型变化的完整指南，请参阅 NEP 50 中的此表格。

主要的向后兼容性问题在于标量的精度。

例如，当运行如下操作时：

np.float32(6) + 6.

返回的是 float32 数据类型而非 float64，这会导致向后兼容困难。为解决此问题，官方建议如下：

显式进行类型转换：使用 int()、float() 或 numpy_scalar.item() 标量显式指定数据类型。

启用警告以追踪变更：通过错误回溯利用警告查找变更。

应对命名空间变更

在 2.0 更新中，大量命名空间移除可能会影响您的代码。NumPy 团队建议采取以下步骤：

1. 查看 已弃用别名与迁移指引。
2. 将已弃用的别名替换为向后兼容的替代方案。
3. 检查 2.0 更新中被移除的私有成员。
4. 如使用了私有成员，请改用现有公共 API。

应对 ABI 破坏

如果您在使用依赖 NumPy C API 的 Python 包，您需要处理 ABI 中的断裂。开发者针对这类情况提供了 NumPy 2.0 专项建议，以解决不兼容问题：

使用 Ruff 插件更新 Python 代码

为帮助您完成迁移，您可以使用 Ruff 插件及其专用的 Ruff 规则 NPY201。

Ruff 可在 PyPI 上以 ruff 获取。要安装 Ruff，请在命令行输入：

pip install ruff

更多详情请参阅 Ruff 安装完整指南。

请在 pyproject.toml 中指定 NP201 规则：

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

或者，您也可以通过命令行指定 NPY201 规则：

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

社区贡献

NumPy 2.0 的发布凝聚了整个社区的努力。通过社区提出的众多 NEP，许多期待已久的提案终于落地。

热情的开发者、研究人员与爱好者在这一里程碑式的发布中发挥了关键作用，他们分享专业知识、提供反馈、提交代码改进，对 NumPy 2.0 产生了深远影响。

结语

NumPy 2.0 为 Python 生态带来了重要跃升，在性能、兼容性与可用性方面引入了众多新功能与改进。如果您在迁移中遇到问题或错误，建议直接与 NumPy 团队沟通。

希望本文有助于您理解此次 NumPy 重要更新中的主要变更。想要更深入了解，请阅读我们的NumPy 教程。

如果您对 NumPy 还不熟悉并希望进一步探索，可尝试我们的NumPy 入门课程，或参加这场NumPy 直播伴学训练。