PyTorch导入时报NumPy版本兼容错误的原因及相关疑问

阿华AIGC实验室

2026-4-13

问题场景

我在MacOS上创建虚拟环境并通过pip安装PyTorch：

python -m env torch-env
source torch-env/bin/activate
pip install torch torchvision torchaudio

但启动Python导入torch时失败，触发以下错误：

Python 3.11.2 (main, Mar  5 2023, 23:08:47) [Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import torch

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.2.4 as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.
Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.

If you are a user of the module, the easiest solution will be to
downgrade to 'numpy<2' or try to upgrade the affected module.
We expect that some modules will need time to support NumPy 2.

Traceback (most recent call last):  File "<stdin>", line 1, in <module>
  File "/Users/ia/torch-env/lib/python3.11/site-packages/torch/__init__.py", line 1477, in <module>
    from .functional import *  # noqa: F403
  File "/Users/ia/torch-env/lib/python3.11/site-packages/torch/functional.py", line 9, in <module>
    import torch.nn.functional as F
  File "/Users/ia/torch-env/lib/python3.11/site-packages/torch/nn/__init__.py", line 1, in <module>
    from .modules import *  # noqa: F403
  File "/Users/ia/torch-env/lib/python3.11/site-packages/torch/nn/modules/__init__.py", line 35, in <module>
    from .transformer import TransformerEncoder, TransformerDecoder, \
  File "/Users/ia/torch-env/lib/python3.11/site-packages/torch/nn/modules/transformer.py", line 20, in <module>
    device: torch.device = torch.device(torch._C._get_default_device()),  # torch.device('cpu'),
/Users/ia/torch-env/lib/python3.11/site-packages/torch/nn/modules/transformer.py:20: UserWarning: Failed to initialize NumPy: _ARRAY_API not found (Triggered internally at /Users/runner/work/pytorch/pytorch/pytorch/torch/csrc/utils/tensor_numpy.cpp:84.)
  device: torch.device = torch.device(torch._C._get_default_device()),  # torch.device('cpu'),

我已经确认使用的是虚拟环境内的Python和pip：

(torch-env) ➜  ~ which pip
/Users/ia/torch-env/bin/pip
(torch-env) ➜  ~ which python
/Users/ia/torch-env/bin/python

当前环境的包列表：

(torch-env) ➜  ~ pip list
Package           Version
----------------- --------
filelock          3.18.0
fsspec            2025.3.0
Jinja2            3.1.6
MarkupSafe        3.0.2
mpmath            1.3.0
networkx          3.4.2
numpy             2.2.4
pillow            11.1.0
pip               22.3.1
setuptools        65.5.0
sympy             1.13.3
torch             2.2.2
torchaudio        2.2.2
torchvision       0.17.2
typing_extensions 4.12.2

我查看了PyTorch仓库的requirements.txt和setup.py，都没有指定NumPy版本限制。我知道可以通过降级NumPy解决问题，但想搞清楚：

为什么PyTorch会用NumPy 1.x编译？
我是不是需要升级pip或pybind11这类工具？
这是不是一个bug？

问题解答

一、核心原因：预编译PyTorch与NumPy 2.x的API冲突

PyTorch的官方预编译安装包（wheel）是基于NumPy 1.x版本编译的，而NumPy 2.x是一个包含重大不兼容API变更的大版本。当你通过pip安装PyTorch时，由于PyTorch的依赖配置没有明确限制numpy<2，pip会自动安装最新稳定版的NumPy（即你环境中的2.2.4），这就导致了：

预编译的PyTorch模块代码依赖NumPy 1.x的底层API
但当前环境使用的NumPy 2.x已经移除/修改了这些API，触发兼容性报错

二、你的疑问逐个解析

1. 为什么PyTorch会用NumPy 1.x编译？

这不是你的操作问题，而是PyTorch官方的发布节奏导致的：
NumPy 2.x发布时间较短，其生态适配还在进行中，PyTorch团队目前仍基于更稳定、生态覆盖更全面的NumPy 1.x来构建官方wheel包，暂未发布兼容NumPy 2.x的正式版本。即使你的环境中有NumPy 2.x，预编译的PyTorch模块依然是针对1.x开发的，因此会出现版本不匹配。

2. 需要升级pip或pybind11吗？

无需升级pip：这个问题与pip版本无关，pip只是按照依赖规则安装了最新版NumPy，核心冲突是PyTorch预编译包的兼容性不足。
pybind11提示与你无关：报错中提到的pybind11>=2.12是给PyTorch开发者的指导——他们需要使用支持NumPy 2.x的pybind11版本重新编译PyTorch代码。作为普通用户，你不需要自行升级pybind11，这是库维护者需要完成的工作。

3. 这是不是一个bug？

严格来说不算“bug”，属于版本迭代中的过渡兼容问题。NumPy 2.x带来了性能优化和架构升级，但也引入了不兼容变更，大部分主流科学计算库都需要时间跟进适配。PyTorch团队后续肯定会发布兼容NumPy 2.x的版本，但目前处于过渡阶段，因此出现了这个冲突。

三、补充：为什么pip会自动安装NumPy 2.x？

因为PyTorch的requirements.txt和setup.py中没有添加numpy<2的版本限制，pip在解析依赖时会默认选择最新的稳定版NumPy。如果PyTorch团队在依赖配置中加入这个限制，就能避免自动安装NumPy 2.x，从而规避这个错误——这可能是他们后续会补上的配置项。