故障排除#

注意

由于这些信息可能会定期更新，请确保您正在查看最新版本的文档。

ImportError#

在某些情况下，安装失败或设置问题可能导致您看到以下错误消息：

IMPORTANT: PLEASE READ THIS FOR ADVICE ON HOW TO SOLVE THIS ISSUE!

Importing the numpy c-extensions failed. This error can happen for
different reasons, often due to issues with your setup.

此错误还包含其他信息，可帮助您进行故障排除。

您的 Python 版本
您的 NumPy 版本

请仔细检查这两者，以确认它们是否符合您的预期。您可能需要检查您的 PATH 或 PYTHONPATH 环境变量（请参见下文的检查环境变量）。

以下各节列出了根据您的设置通常会报告的问题。如果您有认为应该出现的某个问题/解决方案，请提交一个 NumPy issue，以便将其添加。

根据您的系统/设置，有几个常见的问题。如果以下提示均无效，请务必注明以下信息：

您如何安装 Python
您如何安装 NumPy
您的操作系统
您是否安装了多个 Python 版本
如果您是从源代码构建的，请提供您的编译器版本以及理想情况下提供构建日志

在进一步调查和寻求支持时。

使用来自 `conda` (Anaconda) 的 Python#

请确保您已激活您的 conda 环境。另请参阅 conda 用户指南。如果您使用外部编辑器/开发环境，则需要正确设置它。有关一些常见设置的解决方案，请参阅下文。

在 PyCharm 中使用 Anaconda Python#

在 PyCharm 与 Anaconda 一起使用时会遇到一些相当常见的问题，请参阅 PyCharm 支持。

在 VS Code 中使用 Anaconda Python（或环境）#

在 VSCode 中激活环境时，经常会报告一个问题。请参阅 VSCode 支持，了解如何正确设置 VSCode 与虚拟环境或 conda。

在 Eclipse/PyDev 中使用 Anaconda Python（或环境）#

请参阅 Anaconda 文档，了解如何正确配置 Eclipse/PyDev 以使用带有特定 conda 环境的 Anaconda Python。

Windows 上的调试构建#

在 Windows 上，与其在 DEBUG 模式下构建项目，不如尝试在 RELEASE 模式下构建，并包含调试符号但禁用优化。在 Windows 上完全使用 DEBUG 模式会更改 Python 期望找到的 DLL 的名称，因此如果您确实想在 DEBUG 模式下工作，您将需要重新编译您使用的整个 Python 模块堆栈，包括 NumPy。

所有设置#

偶尔可能存在旧的或损坏的 NumPy 安装的简单问题。在这种情况下，您可以尝试卸载并重新安装 NumPy。确保卸载后找不到 NumPy。

开发设置#

如果您使用的是开发设置，请确保运行 git clean -xdf 来删除所有未受版本控制的文件（注意不要丢失您所做的任何修改，例如 site.cfg）。在许多情况下，来自旧构建的文件可能导致不正确的构建。

检查环境变量#

一般来说，如何在您的系统上设置和检查环境变量取决于您的系统。如果您可以打开正确的 Python shell，您也可以在 Python 中运行以下命令：

import os
print("PYTHONPATH:", os.environ.get('PYTHONPATH'))
print("PATH:", os.environ.get('PATH'))

这可能主要有助于您在未运行预期的 Python 和/或 NumPy 版本时解决问题。

下游 ImportError、AttributeError 或 C-API/ABI 不兼容#

如果您看到类似的消息，例如

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.0.0 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'.

作为 ImportError 或使用

AttributeError: _ARRAY_API not found

或其他错误，例如

RuntimeError: module compiled against API version v1 but this version of numpy is v2

或当一个用 Cython 实现的包

ValueError: numpy.dtype size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject

这意味着一个依赖于 NumPy 的包的构建方式与找到的 NumPy 版本不兼容。如果此错误是由于最近升级到 NumPy 2 引起的，最简单的解决方案可能是将 NumPy 降级到 'numpy<2'。

要理解原因，请从回溯（从后往前）中搜索，找到第一个不在 NumPy 内部的行，以确定是哪个包存在不兼容。记下您的 NumPy 版本和不兼容的包版本，以帮助您找到最佳解决方案。

不兼容可能有很多原因：

您最近升级了 NumPy，很可能是升级到了 NumPy 2，而其他模块现在也需要升级。（NumPy 2 于 2024 年 6 月发布。）
您有版本限制，并且 pip 可能安装了不兼容的包组合。
您已本地编译或从其他地方复制了已编译的扩展（通常这是一个坏主意）。

最佳解决方案通常是升级失败的包。

如果您例如通过 pip 安装了它，请尝试使用 pip install package_name --upgrade 进行升级。
如果这是您自己的包或本地构建的，您需要为新的 NumPy 版本重新编译（有关详细信息，请参阅添加对 NumPy 的依赖）。重新安装该包可能足以解决此问题。

当这些步骤失败时，您应该通知包维护者，因为他们可能需要发布一个新的、兼容的版本。

但是，升级并不总是有可能的，因为尚不存在兼容版本，或者由于其他原因无法安装。在这种情况下：

安装兼容的 NumPy 版本
- 尝试使用 pip install 'numpy<2' 降级 NumPy（NumPy 2 于 2024 年 6 月发布）。
- 如果您的 NumPy 版本很旧，您可以尝试升级它，例如使用 pip install numpy --upgrade。
向失败的包添加其他版本固定，以帮助 pip 解析 NumPy 和该包的兼容版本。

分段错误或崩溃#

NumPy 尝试使用高级 CPU 功能（SIMD）来加速操作。如果您收到“非法指令”错误或分段错误，一个原因可能是环境声称支持一项或多项这些功能，但实际上不支持。这可能发生在 Docker 镜像或虚拟机（qemu、VMWare 等）中。

您可以使用 np.show_runtime() 的输出来显示检测到哪些 SIMD 功能。例如：

>>> np.show_runtime()
WARNING: `threadpoolctl` not found in system! Install it by `pip install \
threadpoolctl`. Once installed, try `np.show_runtime` again for more detailed
build information
[{'simd_extensions': {'baseline': ['SSE', 'SSE2', 'SSE3'],
                      'found': ['SSSE3',
                                'SSE41',
                                'POPCNT',
                                'SSE42',
                                'AVX',
                                'F16C',
                                'FMA3',
                                'AVX2'],
                      'not_found': ['AVX512F',
                                    'AVX512CD',
                                    'AVX512_KNL',
                                    'AVX512_KNM',
                                    'AVX512_SKX',
                                    'AVX512_CLX',
                                    'AVX512_CNL',
                                    'AVX512_ICL']}}]

在这种情况下，它会在 found 部分显示 AVX2 和 FMA3，因此您可以尝试在运行 Python 之前在您的环境中设置 NPY_DISABLE_CPU_FEATURES="AVX2,FMA3" 来禁用它们（在 Windows 上使用 cmd.exe）。

>SET NPY_DISABLE_CPU_FEATURES="AVX2,FMA3"
>python <myprogram.py>

通过安装 threadpoolctl，np.show_runtime() 将显示额外信息。

...
{'architecture': 'Zen',
  'filepath': '/tmp/venv3/lib/python3.9/site-packages/numpy.libs/libopenblas64_p-r0-15028c96.3.21.so',
  'internal_api': 'openblas',
  'num_threads': 24,
  'prefix': 'libopenblas',
  'threading_layer': 'pthreads',
  'user_api': 'blas',
  'version': '0.3.21'}]

如果您使用 PyPI 提供的 wheel，它包含来自 OpenBLAS 项目的代码，用于加速矩阵运算。这段代码也可能尝试使用 SIMD 指令。它有不同的选择机制，基于 CPU 架构。您可以覆盖此架构，方法是设置 OPENBLAS_CORETYPE：对于 x86_64，最小值是 OPENBLAS_CORETYPE=Haswell。这也需要在运行 Python 之前设置（这次是针对 posix 系统）。

$ OPENBLAS_CORETYPE=Haswell python <myprogram.py>