故障排除#

注意

由于此信息可能定期更新，请确保您查看的是最新的版本.

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 支持，了解如何使用虚拟环境或 conda 正确设置 VSCode。

使用 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 镜像或 VM（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>
本页面内容