故障排除#

注意

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

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 问题以便添加。

根据您的系统/设置，有一些常见的报告问题。如果以下提示都无法帮助您，请务必注意以下几点

您如何安装 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 以将 Anaconda Python 与特定 conda 环境配合使用。

树莓派#

有时在树莓派上使用 pip3 install（或 pip install）安装时会出现问题。这些问题通常会提到

libf77blas.so.3: cannot open shared object file: No such file or directory

解决方案是

sudo apt-get install libatlas-base-dev

安装自编译 NumPy 所需的缺失库（ATLAS 是线性代数的一个可能提供者）。

或者使用 Raspbian 提供的 NumPy。在这种情况下，运行

pip3 uninstall numpy  # remove previously installed version
apt install python3-numpy

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 之前（对于 Windows 上的 cmd.exe）通过在您的环境中设置 NPY_DISABLE_CPU_FEATURES="AVX2,FMA3" 来尝试禁用它们。

>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>