树莓派上不能只用apt安装python3.11，因其为阉割版：缺_ssl、_lzma、sqlite3等核心模块，且受PEP668限制禁用pip；必须手动编译安装完整版并验证ssl/lzma/sqlite3导入成功。
树莓派上直接用 apt install python3.11 是行不通的——Debian Bookworm（Raspberry Pi OS 默认系统）只提供 python3.11 的核心解释器，但缺编译依赖、lzma 模块、ssl 支持，甚至 pip 都被禁用。必须手动编译安装，否则后续跑 torch、onnxruntime 或 Moondream2 这类模型会卡在 import 失败。
为什么不能只用 apt 安装的 python3.11
系统自带的 /usr/bin/python3.11 是阉割版：它由 python3.11-minimal 包提供，不带 ensurepip、没有 _lzma 和 _ssl 扩展模块，import ssl 直接报错；同时受 PEP 668 限制，pip3 install 会被拒绝，提示 externally-managed-environment。
- 验证方法：
/usr/bin/python3.11 -c "import ssl; print('ok')"→ 报ModuleNotFoundError - 真实项目（如 YOLOv5、Moondream2）依赖完整标准库，尤其
ssl（HTTPS 下载权重）、lzma（解压模型）、sqlite3（缓存管理） - 系统包管理器不会为你补全这些，也不允许你用 pip 覆盖系统 Python
手动编译 Python3.11 的关键步骤
目标是生成一个独立、完整、可部署的 Python 安装，路径建议设为 /usr/local/python311，避免污染系统路径。
- 先装齐编译依赖：
sudo apt install -y build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libsqlite3-dev libreadline-dev libffi-dev libbz2-dev liblzma-dev - 下载源码并解压：
wget https://www.python.org/ftp/python/3.11.0/Python-3.11.0.tgz && tar xzf Python-3.11.0.tgz - 配置时必须加关键参数：
./configure --prefix=/usr/local/python311 --enable-optimizations --with-lto --with-system-ffi --with-system-expat --with-lzma --enable-loadable-sqlite-extensions --with-ensurepip=yes --program-suffix=311 - 编译安装（树莓派5约需 50–70 分钟）：
make -j$(nproc) && sudo make install - 验证：
/usr/local/python311/bin/python3.11 -c "import ssl, lzma, sqlite3; print('all ok')"
虚拟环境必须基于新 Python，且不能用 system-site-packages
直接用系统 python3 -m venv 创建的环境仍继承受限的解释器。正确做法是用新安装的 Python 创建干净隔离环境：
立即学习“Python免费学习笔记（深入）”；
- 创建：
/usr/local/python311/bin/python3.11 -m venv ~/venv311 - 激活后立即升级 pip：
source ~/venv311/bin/activate && python -m pip install --upgrade pip - 禁止使用
--system-site-packages：它会把系统/usr/lib/python3.11下残缺模块混进来，导致运行时随机 import error - 安装 wheel 包（如
torch）前，确认python -c "import sys; print(sys.base_prefix)"输出是~/venv311，不是/usr
常见坑：GPIO 权限、systemd 服务与 Python 路径绑定
很多用户装完 Python3.11 后发现 RPi.GPIO 或 gpiozero 在虚拟环境中无法操作引脚——这不是权限问题，而是 Python 解释器路径没对齐。
-
RPi.GPIO是 C 扩展模块，编译时硬编码了 Python ABI 版本和头文件路径；必须用同一套源码重新编译：pip install --no-binary RPi.GPIO RPi.GPIO - 如果用 systemd 写开机服务（比如气象站采集脚本），
ExecStart=必须写死完整路径：/home/pi/venv311/bin/python /home/pi/weather_station.py，不能只写python或python3.11 - 别把
/usr/local/python311/bin加进PATH全局生效——这会让系统工具（如apt自带的 python3 脚本）意外调用新版解释器，引发不可预知错误
最易被忽略的一点：编译时漏掉 --with-lzma 或 --with-ssl，会导致后续所有模型加载失败，但错误信息非常模糊（比如 OSError: Unable to load library 'lzma' 或 urllib.error.URLError: <urlopen error wrong_version_number>），排查起来要花几小时翻日志。务必在 <code>make install 后立刻验证三个核心模块。
