[树莓派] 解决 Pyenv 虚拟环境下 Picamera2 无法加载 libcamera 的问题

前言

最近在使用树莓派进行机器视觉开发时，遇到了一个棘手的环境问题。在使用 pyenv 管理的 Python 环境中运行 picamera2 时，程序无法找到系统级的 libcamera 库。本文记录了从排查到解决的完整过程，希望能帮助遇到同样问题的朋友。

1. 问题复现

在 Raspberry Pi OS 上，使用 pyenv 创建的 Python 环境运行代码：

1
2
3
from picamera2 import Picamera2
# 或者
import libcamera

报错信息：

1
2
3
4
5
6
Traceback (most recent call last):
  File "camera_test.py", line 2, in <module>
    from picamera2 import Picamera2, Preview
  File "/path/to/site-packages/picamera2/__init__.py", line 4, in <module>
    import libcamera
ModuleNotFoundError: No module named 'libcamera'

2. 深度解析：为什么会报错？

这个问题的本质是 Python 环境隔离 与 系统级依赖 之间的冲突。

  1. libcamera 的特殊性：libcamera 的 Python 绑定并非通过 pip 安装的标准包，而是通过系统包管理器（apt）安装的（python3-libcamera），它位于系统的 /usr/lib/python3/dist-packages 目录下。
  2. Pyenv 的隔离机制：pyenv 安装的 Python 版本（如 3.9.18）是独立编译的，默认无法“看到”系统的 dist-packages。
  3. 错误的虚拟环境基底：通常我们习惯用 python -m venv 创建虚拟环境。如果当前处于 pyenv 激活状态，这个 python 指向的是 pyenv 的版本，而非系统自带的 /usr/bin/python3。这导致即使加了 --system-site-packages 参数，也无法链接到系统级的 libcamera。

3. 排查与修复实战

为了彻底解决问题，我采用了“自下而上”的验证方法，确保硬件、驱动、系统环境无误后，再修复 Python 环境。

第一步：验证系统底层（排除硬件问题）

首先，暂时屏蔽 pyenv，确保使用的是树莓派原生系统环境。

  1. 临时清理环境变量（在当前终端执行）：

    1
    2
    unset PYENV_ROOT
    export PATH=$(echo $PATH | sed 's|/home/sandocean/.pyenv/shims:||' | sed 's|/home/sandocean/.pyenv/bin:||')

  2. 测试摄像头驱动：
    运行 libcamera-hello。如果屏幕出现 5 秒预览，说明硬件和底层驱动正常。

  3. 验证系统 Python：
    使用系统绝对路径的 Python 尝试导入：

    1
    /usr/bin/python3 -c "import libcamera; print(libcamera)"

    预期结果：无报错，且打印出模块路径（如 /usr/lib/python3/dist-packages/...）。

第二步：创建“混合型”虚拟环境（核心解决方案）

既然 libcamera 依赖系统环境，我们需要基于系统 Python 来创建虚拟环境，并通过参数打通系统包的访问权限。

  1. 清理旧环境：删除之前创建失败的 venv 文件夹。

  2. 使用绝对路径创建环境（关键步骤）：
    不要直接用 python，而是指定 /usr/bin/python3。

    1
    2
    # 假设在项目根目录
    /usr/bin/python3 -m venv venv --system-site-packages

    注意：--system-site-packages 参数是必须的，它允许虚拟环境访问系统的 apt 安装包。

  3. 激活并验证：

    1
    2
    3
    4
    source venv/bin/activate

    # 再次验证导入
    python -c "import libcamera; print('Success!')"

4. 总结与避坑

解决此问题的关键在于理解：picamera2 和 libcamera 强依赖于树莓派系统的 apt 包。

  • ❌ 不要 试图在纯净的 pyenv 版本（如 3.10.x）中通过 pip 安装 libcamera（源里没有这个包）。
  • ✅ 正确做法：使用系统自带的 /usr/bin/python3 作为基底创建虚拟环境，并开启 --system-site-packages。

这样既能享受虚拟环境带来的包管理便利，又能顺利调用系统级的硬件驱动库。