QPython 包安装失败排查——网络、编译、版本三大原因

三大常见失败原因

QPython 上安装第三方包失败，90% 的情况属于以下三类之一：

原因一：网络问题

现象：下载进度卡住、超时、报网络连接错误。

排查和解决：

• 检查网络连接是否正常：在 QPython 里 import requests; requests.get("https://pypi.org", timeout=5) 试试
• 确认用的是 Wi-Fi（移动网络可能限速或不稳定）
• QPYPI 是从 PyPI 拉包，PyPI 服务器在国外，国内访问可能需要镜像：
• 终端里临时换镜像：subprocess.run(["pip", "install", "numpy", "-i", "https://pypi.tuna.tsinghua.edu.cn/simple"])
• 永久配置（QPython 版本可能不支持全局 pip 配置）

原因二：需要编译 C 扩展

现象：下载完源码后开始编译，报 error: command 'gcc' not found 或类似错误。

原因：某些 Python 包包含 C / C++ 扩展代码，安装时需要编译。Android 上没有编译工具链（GCC / Make），所以编译失败。

判断方法：看报错里有没有 error: command 或 gcc、g++、make 字样。

解决方法：

1. 放弃这个包：换一个功能类似但纯 Python 实现的替代包
2. 找预编译的 wheel：如果包提供 .whl 格式的预编译文件，可以手动下载安装
3. 在 PC 上编译好再拷过来：比较折腾，不推荐

纯 Python 包基本都能装。有 C 扩展的包（如 scipy、opencv-python、Pillow 的某些版本）成功率较低。

原因三：版本不兼容

现象：安装成功但 import xxx 时仍报错，或者安装过程报依赖版本冲突。

排查：

# 查看当前 Python 版本
import sys; print(sys.version)

# 确认包名和导入名是否一致
# 比如 pip install Pillow 但代码里是 from PIL import Image

解决：

• 卸载冲突包，先装一个再装另一个
• 找旧版本的包（某些新版本可能不兼容当前 Python 版本）
• 放弃同时安装两个有冲突依赖的包

安装后的验证

装完一个包后，务必验证一下：

import numpy
print(numpy.__version__)  # 能输出版本号 = 成功

如果 QPYPI 显示安装成功但 import 还是失败：

1. 重启 QPython App（有时新安装的包需要重启才能被 Python 运行时识别）
2. 检查包名和导入名是否不同（常见坑：pip install Pillow → from PIL import Image）
3. 确认包确实在已安装列表里（QPYPI 的已安装 Tab）

特殊情况

安装中途退出 QPython

如果安装过程中 QPython 被系统杀掉（可能因为下载占用太多内存）：

• 重新打开 QPython
• 再次 pip install，pip 有缓存，会跳过已下载的部分
• 装大包裹低优先级进行：不要同时做其他事情、不要开后台运行的脚本

安装速度很慢

• PyPI 默认服务器在国外，国内用户可以换国内镜像加速
• 手机本身下载速度比 PC 慢，包越大越明显
• 耐心等——pip 不会中途丢数据（断点续传）

部分版本的 pip 问题

极少数 QPython 版本的内置 pip 可能有 Bug。如果遇到奇怪的问题：

• 更新 QPython 到最新版
• 或尝试用 subprocess.run(["pip", "--version"]) 确认 pip 是否正常

小结

包安装失败三大原因：网络（换 Wi-Fi / 镜像）、C 扩展编译（无解，换纯 Python 替代）、版本冲突（卸载重装 / 换旧版本）。装完必用 import + __version__ 验证。PyPI 在国内可能慢，记得加国内镜像源。

继续看电池优化——脚本长时间运行被杀的头号原因。