迁移到 Python 3.12 后，NumPy 核心接口对终端用户基本保持兼容，但必须升级 NumPy 版本以适配解释器移除 distutils 模块和 C-API 变更。主要风险集中在旧版 NumPy 无法在 3.12 环境安装，而非代码逻辑报错。

命令速用版

在升级 Python 解释器后，优先执行以下命令更新 NumPy 及相关科学计算库，避免导入错误。

pip install `--upgrade` numpy
pip install `--upgrade` scipy pandas

若使用 conda 环境，建议创建新环境而非原地升级，确保二进制依赖干净。

conda create -n py312_env python=3.12 numpy pandas
conda activate py312_env

为什么会这样

核心原因是 Python 3.12 标准库移除了 distutils 包，且 C-API 进行了清理。

公开资料明确显示，Python 3.12 的标准库变更主要集中在清理已弃用的 API，其中 distutils 包已从标准库中移除。旧版 NumPy（如 1.21.x 及更早）在安装或构建时依赖 distutils，因此在 3.12 环境下会直接失败。此外，NumPy 官方兼容性列表指出，NumPy 1.21.x 支持 Python 3.7 到 3.10，这意味着 3.11 和 3.12 需要更新的 NumPy 版本。对于大多数只调用 numpy.array 等高层接口的用户，代码无需修改，但底层依赖必须更新。

分步处理

按以下顺序操作，可确保迁移过程可控，避免环境污染。

第一步：检查当前版本映射

确认项目当前使用的 NumPy 版本。若版本低于 1.22，必然不兼容 Python 3.12。参考公开兼容性资料，NumPy 1.20.x 支持 Python 3.6 到 3.9，1.21.x 支持到 3.10。

第二步：升级解释器与包

先切换 Python 解释器至 3.12，再安装新包。不要尝试在 3.12 上强制安装旧版 wheel。

python3.12 -m pip install `--upgrade` pip
python3.12 -m pip install "numpy>=1.26"

第三步：处理第三方依赖

检查 scipy、pandas、matplotlib 等依赖 NumPy 的库。这些库同样需要适配 Python 3.12 的新 ABI。

怎么验证是否生效

通过以下脚本验证导入是否成功及版本是否符合预期。

import numpy as np
import sys
print(f"Python: {sys.version}")
print(f"NumPy: {np.__version__}")
print(np.array([1, 2, 3]).sum())

若脚本无报错且输出结果正确，说明基础兼容性已通过。对于复杂项目，需运行单元测试 suite 确认数值计算精度无回归。

常见坑

迁移过程中有几个高频错误点，需提前规避。

• 编译报错：若 pip 安装时出现 error: command 'gcc' failed 或提及 distutils，说明正在尝试编译不支持 3.12 的旧版源码包，必须换用预编译 wheel 或升级库版本。
• 隐式依赖：某些库内部依赖旧版 NumPy 接口，升级主库后若报错，需同步升级其子依赖。
• 虚拟环境残留：原地升级 Python 解释器可能导致虚拟环境内二进制文件失效，建议重建虚拟环境。

常见问题

Python 3.12 上能安装 NumPy 1.21 吗？

不能。公开兼容性资料显示 NumPy 1.21.x 仅支持到 Python 3.10，3.12 需要更新版本。

迁移后代码需要修改吗？

通常不需要。NumPy 高层接口保持稳定，主要工作量在环境配置和依赖升级。

遇到 ImportError: cannot import name 'Mapping' 怎么办？

这是 Python 3.12 移除 collections.Mapping 导致的，需升级涉及到的第三方库（如 werkzeug 等），与 NumPy 无直接关系但常同时出现。

参考来源

• python 版本和对应的 numpy - 关于 NumPy 与 Python 版本支持范围的说明
• Python 3.12 有什么新变化 - 关于 distutils 移除及标准库变更的说明
• Python 3.9 到 3.12 的迁移过程中有哪些 Web 开发的断层变化？ - 关于 Python 3.12 兼容性问题核心及标准库精简的说明