企业官网建设流程全解析

MediaPipe Python 环境部署报导入错误？3 步定位并修复

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe

pip install装完 mediapipe，脚本一跑就中断，终端抛出ImportError: cannot import name 'Sequence' from 'collections'，或者ModuleNotFoundError: No module named 'mediapipe.python._framework_bindings'。这类报错的本质是 Python 解释器版本、依赖库版本和预编译包三者没对齐。照这篇文章操作，大约 10 分钟能完成诊断和修复。

最短解决路径

三条命令先让环境跑起来（以 Linux/macOS 为例，Windows 把python3换成py -3.11即可）：

python -m venv mp-env source mp-env/bin/activate pip install "mediapipe>=0.10"

装完后跑一句import mediapipe as mp，不再报导入错误就说明包与解释器匹配了。注意 mediapipe 的 wheel 按 Python 小版本单独编译，3.10 的装不进 3.11 的环境，这是绝大多数"装上了却用不了"的根源。

报错背后发生了什么

mediapipe 的 Python 层不只是纯 Python 代码，packet_creator、packet_getter这些模块最终都链接到 C++ 扩展_framework_bindings。这个扩展是二进制文件，编译时锁定了当时的 Python ABI 和 numpy 二进制接口。三件事没对齐，导入链就会断：

1. 解释器小版本与 wheel 不一致，动态库加载失败；
2. 环境里的 numpy 比 wheel 编译时新，ABI 校验不通过；
3. 第三方库（比如你另装的 opencv）把共享依赖顶掉。

当前仓库里 packet_creator.py 已经只用typing做类型注解，不再依赖旧式collections导入，所以升级包版本本身就能消掉第三类报错。

关键配置逐项说明

环境隔离：venv 是唯一可靠的开关

系统全局环境里常残留旧 numpy、旧 protobuf，装什么都容易互相顶版本。troubleshooting.md 里列的ImportError: No module named numpy就是全局污染后的典型症状。每接一个项目就新建一个 venv，把解释器版本钉死，后面所有排查都有确定基准。

选对依赖锁文件

仓库根目录提供了四个锁定文件，都由 pip-compile 在对应解释器上生成：

• requirements.txt：上游依赖声明，只写宽松范围（absl-py~=2.3、numpy、opencv-contrib-python等）；
• requirements_lock.txt：Python 3.9 生成，文件头第 2 行注明了这一点；
• requirements_lock_3_10.txt、requirements_lock_3_11.txt、requirements_lock_3_12.txt：分别对应 3.10 到 3.12。

选择规则很直接：你的解释器是什么小版本，就用哪个锁文件。装之前可以先看文件头几行的 pip-compile 注释，确认生成用的 Python 版本。

从源码编译：两个开关别漏

如果官方 wheel 不覆盖你的平台（比如较新的 Python 小版本），只能走 setup.py 编译，此时环境要求完全不同：

export MEDIAPIPE_DISABLE_GPU=1 python setup.py bdist_wheel

MEDIAPIPE_DISABLE_GPU=1关闭 GPU 依赖，跳过 EGL、Metal 相关编译；setup.py 开头还会强制检查 Bazel 版本不低于 3.4.0，版本过低会直接sys.exit(-1)。源码编译耗时以小时计，能装到预编译 wheel 就不要走这条路。

验证是否生效

四个检查点，前三个不到 1 分钟：

1. python -c "import mediapipe as mp"——确认核心包与解释器匹配；
2. python -c "import mediapipe as mp; print(mp.__version__)"——确认是目标版本，而不是环境里残留的旧版；
3. python -m unittest discover mediapipe/python——仓库自带的 单元测试 能跑通，说明导入链完整；
4. 打开一张图跑一次最小任务（如 face detector），输出结果文件存在且非空，才算端到端可用。

常见问题

Q：pip check 提示 protobuf 或 opencv 版本冲突，修哪个？先动 numpy，再动 protobuf。mediapipe 的扩展库对 numpy ABI 最敏感；protobuf 冲突通常表现为AttributeError，按锁文件降级即可，不需要升级。

Q：3.12 环境装完 wheel，运行时报动态库缺失？大概率是装了 3.10/3.11 的 wheel。用pip show mediapipe看文件路径，确认 wheel 文件名里的cp312标签，不对就卸载重装。

Q：想跑官方示例但依赖太多怎么办？只装 requirements.txt 里和你用到的模块相关的条目即可，比如只做图像任务就跳过音频相关的sounddevice。

延伸阅读

• Python 入门文档
• 安装指南
• 开发协作说明

把解释器版本、锁文件、wheel 三者对齐，导入类报错基本都能收敛。

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe