企业官网建设流程全解析

ImportError 别慌：3 步搞定 MediaPipe Python 兼容性报错

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

pip 装完 mediapipe，一 import 就报cannot import name 'Sequence' from 'collections'？对，就是那个红字。这类 MediaPipe Python 兼容性问题，九成出在 Python 版本和依赖树，照下文改完就能跑。

先对号入座：你的报错是哪一类

常见的 MediaPipe ImportError 修复路径就三条，先确认你中哪一条。

导入路径报错：collections 里找不到 Sequence

collections.Sequence在 Python 3.10 被正式移走，老代码还按旧路径导入就炸。当前仓库的mediapipe/python/packet_creator.py已经改用 typing 导入，所以这行报错多半来自你自己的脚本或旧第三方包，不用怀疑仓库源码。Python 3.9 及以下不受影响，但官方支持线已经拉到 3.9 起步，建议顺手升级。

依赖版本打架：numpy 和预编译二进制不匹配

requirements.txt只写包名不写版本，pip 默认拉最新；numpy 一到 2.x，ABI 就变了，而 mediapipe 和 opencv 的轮子是按 1.26 编译的，于是报numpy.dtype size changed, C API may be incorrect。这是 MediaPipe 依赖冲突解决里最高频的一类，pip show numpy看一眼版本就能确认。同理，protobuf 版本和轮子编译时用的不一致时，import 阶段也可能抛错。

系统调用受限：libGL 或音频设备找不到

无显示器的 Linux 上 import 挂在libGL.so.1，是系统缺图形库，和包本身无关；Windows 或 macOS 上sounddevice报 PortAudio 错误，则是音频驱动没装好或设备被占用。

别慌，下面逐个修。

对症修复：MediaPipe 兼容性按版本一次对齐

每个版本只给最小改动，改完跑import mediapipe验证。

Python 3.10：把 Sequence 的导入换到 collections.abc

打开报你名字的那个脚本，找到这行：

from collections import Sequence # 报错的就是它 from collections.abc import Sequence # 改成这行

就改一行，语义完全一样：collections.abc 是官方迁移后的新家，两个名字指的是同一个抽象基类。如果是旧版 mediapipe 轮子里带出来的，直接pip install -U mediapipe升到新版绕开，不用去动 site-packages。

Python 3.11 安装 MediaPipe：装完先对齐两个依赖

3.11 上最容易翻车的还是 numpy。仓库根目录的requirements_lock_3_11.txt已经把版本钉死：numpy==1.26.4、protobuf==4.25.5，照着对齐就行：

pip install mediapipe pip install "numpy==1.26.4" "protobuf==4.25.5"

先装 wheel 再钉版本，顺序别反，否则 pip 的解析器可能又给你升回去。钉完跑一下python -c "import mediapipe as mp; print(mp.__version__)"，能打印版本号就通了。

Python 3.12：直接用锁定文件装依赖

setup.py里官方标注支持 3.9 到 3.12，3.12 本身没有兼容坑，关键还是别让 pip 装到 numpy 2.x。手里有仓库源码的话，一条命令最省事：pip install -r requirements_lock_3_12.txt，再补一个pip install mediapipe。锁定文件是 pip-compile 自动生成的，依赖树和开发环境一致，装完基本不用二次排查；从源码构建时，文件里的 jax、sentencepiece 也会按同一版本装齐，省掉反复试错。没克隆仓库的话，照 3.11 的钉版本方式做即可。

把环境焊死：venv + 锁定文件

换台机器、交给同事，环境别从零重来。我每次都是这么搞的：

python -m venv mp_env --python=3.11 # 隔离环境，钉住 Python 版本 source mp_env/bin/activate # 激活，Windows 用 mp_env\Scripts\activate pip install -r requirements_lock_3_11.txt # 依赖版本一次钉死 pip install mediapipe # 最后装本体

四步走完，venv 记录解释器和顶层包，锁定文件记录每个依赖的精确版本，两层一起才叫焊死，同事照着这四条命令走，装出来的环境和你这台一模一样。依赖要更新时，跑一句pip-compile --output-file=requirements_lock_3_11.txt requirements.txt重新生成即可，它的作用就是把可解析的依赖树落成精确版本，不用手改；以后每次升级都重新编译一遍锁定文件，团队里就不会各装各的了。

换机器之前看一遍

• ⚠️先建 venv 再装包，别裸装系统环境
• 锁定文件跟着版本选，_3_11 和 _3_12 别混着装
• numpy 先钉 1.26，2.x 等官方适配
• 报错读最后一行，ImportError 根因在最后
• 无头 Linux 缺libGL是系统问题，装图形库就行
• sounddevice 报错先查设备占用和驱动
• ✅ 顺序别乱：导入 → 依赖 → 系统库

跑通了就收藏这篇，下次换环境回来翻就行。遇到表里没覆盖的报错，去项目 issue 里搜一下，多半已经有人踩过同一条坑。

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