运行MediaPipe报TypeError:Descriptors cannot be installed directly

报错根因 #

当前环境安装的protobuf Python包版本≥3.21.0，而MediaPipe安装包内预置的_pb2.py文件由低于3.19.0版本的protoc编译生成，新旧版本protobuf的描述符加载API不兼容，触发类型错误。 #

方案1：版本适配（长期使用首选，无性能损耗） #

安装兼容旧pb文件的最新稳定版protobuf，无需修改代码、无额外性能损失，是生产环境的标准解法：

pip install protobuf==3.20.3

安装完成后执行pip show protobuf确认版本为3.20.3，重新运行原脚本即可正常启动。3.20.x是protobuf最后一个兼容旧版protoc生成代码的维护分支，3.20.3为该分支最终修复版本，Python 3.7环境下无已知兼容问题。 #

方案2：环境变量绕过（仅用于临时调试） #

若暂时无法调整依赖版本，可通过设置环境变量强制protobuf使用纯Python解析逻辑绕过版本检查。该方案会使protobuf解析速度下降40%~70%，MediaPipe实时推理帧率会明显降低，不适合长期使用。
不同终端下的临时设置命令如下：

• Windows CMD（当前窗口生效）：

set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python

• Windows PowerShell（当前窗口生效）：

$env:PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION="python"

• Linux/macOS Bash/Zsh（当前窗口生效）：

export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python

设置完成后在同一终端窗口运行脚本即可。不建议将该变量写入全局环境变量，会拖慢所有依赖protobuf的Python程序运行速度。 #

不推荐操作 #

报错提示中提到的「使用≥3.19.0版本protoc重新生成_pb2.py文件」方案不适用于普通用户：MediaPipe的pb文件与内置C++推理扩展版本强绑定，自行重新生成的pb文件大概率出现字段不匹配、序列化失败等问题，除非从源码完整编译整套MediaPipe，否则不要使用该方案。

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