疑难解答#

注意

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

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 支持，了解如何使用虚拟环境或 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 镜像或虚拟机 (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>