树莓派5使用Picamera2库报错：module 'kms' has no attribute 'PixelFormat'

问题根源 #

这个错误是因为Picamera2依赖的libcamera或kms组件版本不兼容，树莓派5的系统环境里kms模块API有变更，导致找不到PixelFormat属性。

修复步骤 #

• 全量升级系统组件
  先更新系统所有包，确保底层驱动和依赖是最新的：

  sudo apt update && sudo apt full-upgrade -y
  sudo reboot
  

• 重装适配树莓派5的Picamera2
  卸载现有版本后，安装官方适配的包：

  pip uninstall -y picamera2
  sudo apt install -y python3-picamera2 libcamera-apps-lite
  

• 调整代码格式配置
  改用libcamera原生支持的格式，避免兼容性问题，修改代码里的摄像头初始化部分：

  picam2 = Picamera2()
  # 使用YUYV格式，后续转RGB更稳定
  config = picam2.create_preview_configuration(main={"format": "YUYV", "size": (640, 480)}, preview=None)
  picam2.configure(config)
  picam2.start()
  

  捕获帧后的格式转换也要对应修改：

  frame = picam2.capture_array()
  # YUYV转RGB格式
  rgb_frame = cv2.cvtColor(frame, cv2.COLOR_YUV2RGB_YUYV)
  

• 检查kms驱动加载状态
  执行命令确认kms驱动是否加载：

  lsmod | grep kms
  

  如果没有输出，需要启用kms驱动：编辑/boot/firmware/config.txt，添加或修改一行：

  dtoverlay=vc4-kms-v3d
  

  保存后重启系统。

额外验证 #

• 用libcamera-hello命令测试摄像头，如果能正常显示画面，说明硬件和libcamera驱动没问题。
• 尽量用系统默认Python环境运行代码，避免虚拟环境的依赖隔离导致问题。

内容的提问来源于stack exchange，提问作者Bsaka