ARMv7l 安装 NumPy 失败怎么办？ninja wheel、Python 版本与 Klipper 环境

作者

ARMv7l 电视盒子安装 NumPy 时出现 “Failed building wheel for ninja” 或 PEP 517 编译失败，通常表示 PyPI 没有适合当前 Python、系统和架构的预编译 wheel，pip 只能在低内存设备上从源码构建。优先使用系统仓库的 python3-numpy，Klipper 用户则必须在实际使用的虚拟环境里安装。

版本提醒：旧文在 Python 3.9、ARMv7l、约 1GB 内存环境中验证了 NumPy 1.21.2，但这不是所有设备的通用版本。Python 版本不同，应根据 NumPy 的 Python 要求选择版本，不能无条件降级。

先检查 ARM 架构、Python 和 Klipper 环境

uname -m
python3 --version
python3 -m pip --version
free -h
df -h
ls -d ~/klippy-env 2>/dev/null

armv7l 是 32 位 ARM。很多新版本科学计算包不再为它提供 wheel；1GB 内存还可能在 C/C++ 编译阶段耗尽。先确认 Klipper 是使用系统 Python，还是 ~/klippy-env 虚拟环境。

方法一：优先安装系统仓库的 python3-numpy

sudo apt update
sudo apt install python3-numpy
python3 -c "import numpy; print(numpy.__version__)"

Debian/Ubuntu/Armbian 仓库通常会提供针对该发行版架构构建好的 NumPy，虽然版本未必最新，但比在小内存 ARMv7l 设备上本地编译稳定。若 Klipper 使用独立虚拟环境，系统包默认不会自动出现在其中。

方法二：在 Klipper 虚拟环境中安装兼容版本

先用虚拟环境自己的 Python 和 pip，避免“终端里能 import，Klipper 里却找不到”的情况：

~/klippy-env/bin/python --version
~/klippy-env/bin/python -m pip install --upgrade pip setuptools wheel
~/klippy-env/bin/python -m pip install "numpy==1.21.2"
~/klippy-env/bin/python -c "import numpy; print(numpy.__version__)"

上面的固定版本只对应原测试环境。若 Python 不是 3.9，应先查看 pip 报错中的 Requires-Python，再选择兼容版本。不要为了装 NumPy 随意替换 Klipper 自带 Python。

为什么 ninja、patchelf 或 PEP 517 会失败

  • PyPI 没有匹配 linux_armv7l 和当前 Python ABI 的 wheel。
  • pip 下载的是 .tar.gz 源码包，需要编译 NumPy 和构建依赖。
  • 设备内存或交换空间不足，编译进程被系统终止。
  • 编译器、Python 开发头文件、BLAS/LAPACK 或 Rust/CMake/Ninja 依赖不完整。
  • 镜像源同步不完整或只缓存了源码包。

必须源码编译时需要什么

只有系统仓库和兼容旧版都不能满足功能需求时，才考虑源码编译。先备份 Klipper 配置，并准备足够磁盘和交换空间：

sudo apt install build-essential python3-dev gfortran 
    libopenblas-dev liblapack-dev pkg-config

~/klippy-env/bin/python -m pip install --no-cache-dir numpy

ARMv7l 上编译可能持续很久并产生高温。不要在打印任务进行中编译，也不要把别的 Python 环境里的 site-packages 目录直接复制进 Klipper；二进制扩展的 ABI 不一致时会产生更隐蔽的崩溃。

如何确认 NumPy 对 Klipper 生效

~/klippy-env/bin/python -c "import sys, numpy; print(sys.executable); print(numpy.__version__)"
sudo systemctl restart klipper
sudo systemctl status klipper --no-pager

确认输出的 Python 路径来自 klippy-env，再观察 Klipper 日志。仅仅看到 pip 显示“Successfully installed”并不能证明服务使用的是同一个环境。

相关阅读