树莓派pip安装常卡在“Building wheel”阶段，因ARM架构编译资源有限、默认swap仅100MB，编译大库易OOM导致假死；需增大swap、换清华源（含apt主源、raspi.list和pip.conf）、优先用apt装预编译包（如sudo apt install python3-opencv），或强制二进制安装。
树莓派上直接用系统自带的 Python 3 就能跑基础脚本，但想稳定装 OpenCV、NumPy 或 PyTorch 这类库，不调内存和源，pip install 很可能卡死、报错或装一半失败。
为什么树莓派 pip 安装常卡在“Building wheel”阶段
ARM 架构编译资源有限，很多包默认走源码编译（尤其是没提供 manylinux_aarch64 轮子的），而树莓派默认只分配 100MB 左右的 swap 空间，gcc 编译 OpenCV 这种大库时直接 OOM —— 表现为终端假死、KeyboardInterrupt 也无效、风扇狂转。
- 检查当前 swap 大小：
swapon --show - 临时增大 swap（重启失效）：
sudo dphys-swapfile swapoff && sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile && sudo dphys-swapfile setup && sudo dphys-swapfile swapon - 别长期开着 2GB swap：SD 卡写入寿命会明显下降，仅在编译时启用，装完立即降回 100MB
换清华源后 pip install 仍超时或 404？检查两个 list 文件
树莓派默认用 raspbian.raspberrypi.org，国内访问极慢且易中断；只改 /etc/apt/sources.list 不够，pip 用的是 PyPI 源，而系统里还藏着一个 raspi.list 控制硬件相关包源 —— 这个漏改，sudo apt install python3-opencv 会直接失败。
- 改 apt 源：
sudo nano /etc/apt/sources.list，替换为清华镜像（注意路径中的bookworm或bullseye要和你系统一致） - 改 raspi 源：
sudo nano /etc/apt/sources.list.d/raspi.list，同样换成清华地址 - 改 pip 源：创建
~/.pip/pip.conf，写入：[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple/ trusted-host = pypi.tuna.tsinghua.edu.cn
OpenCV / PyTorch 这类大库，优先用 apt 装而非 pip
树莓派官方源已预编译好适配 ARM64 的二进制包，跳过编译省下 20 分钟以上，且依赖自动解决。但要注意版本较旧（例如 python3-opencv 当前是 4.7.x，不是最新 4.10），对功能要求不高的项目足够用。
立即学习“Python免费学习笔记（深入）”；
- 装 OpenCV：
sudo apt install python3-opencv（验证：python3 -c "import cv2; print(cv2.__version__)"） - 装 PyTorch（Bookworm）：
sudo apt install python3-torch python3-torchvision（注意：无 CUDA，纯 CPU 推理） - 如果必须新版 pip 包：先
pip install --only-binary=all --no-cache-dir opencv-python，强制跳过编译
虚拟环境必须加 --system-site-packages 吗？
不必须，但对树莓派很实用。系统级 apt 安装的库（如 python3-opencv）默认不在 venv 隔离范围内，直接 python3 -m venv myenv 后 import cv2 会报错。
- 让 venv 能访问系统库：
python3 -m venv --system-site-packages myenv - 缺点：失去部分隔离性；优点：避免重复安装大库、节省空间、启动更快
- 更安全的做法：用 Miniconda3 替代 venv（它默认复用系统库且管理更稳），但需额外下载 conda-arm64 安装包
真正麻烦的不是步骤多，而是某一步漏掉（比如没动 raspi.list），后面所有 pip 和 apt 命令都慢得像拨号上网——这种延迟感最容易让人放弃调试。
