MediaPipe 人脸检测安装指南：一条 pip 命令装好，附报错对照表
【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe
MediaPipe 是跨平台实时媒体机器学习框架，能跑人脸检测、手势识别、前景分割。最小行动就一条命令：pip install mediapipe。当前版本 1.1.0，见 mediapipe/version.bzl。
先确认走哪条路线
| 你的情况 | 建议路线 |
|---|---|
| Python 脚本 / 应用，不改源码 | pip install mediapipe，走下文"安装主线" |
| C++ / Android / iOS 原生应用 | 按平台文档用 Bazel 构建，无需本地编译 Python 包 |
| 改源码、加 Calculator、提交贡献 | 源码编译 Python 包，见"源码编译"一节 |
PyPI 现成轮子覆盖 x86_64 Linux、x86_64 macOS 10.15+、amd64 Windows，均为 64 位 Python；aarch64 Linux（Jetson、树莓派）无官方轮子，只能源码编译，见 docs/getting_started/python.md 与 docs/getting_started/troubleshooting.md。
装前环境自检
| 检查项 | 标准 | 快速确认方法 |
|---|---|---|
| Python 版本 | 3.9–3.14，64 位 | python3 --version，依据 setup.py |
| pip 与 python 同一解释器 | 二者指向一致 | pip --version里的路径含你的 venv |
| Bazel ≥ 3.4.0 | 仅源码编译场景需要 | bazel --version，依据 setup.py |
| OpenCV | 3.x–4.1 优先 | 仅源码编译且用--link-opencv场景需要，依据 docs/getting_started/install.md |
| gcc/g++ 版本 | 避开 6.3 和 7.3 | 仅 TensorFlow Calculator 场景需要，依据 docs/getting_started/install.md |
安装主线：三步装好核心包
第 1 步：隔离安装，不污染系统环境。
python3 -m venv mp_env && source mp_env/bin/activate通过信号：提示符前出现(mp_env)。没有该前缀说明没激活，后面会装错位置；Windows 改用mp_env\Scripts\activate。
第 2 步：装预编译轮子。
pip install mediapipe通过信号：结尾出现Successfully installed mediapipe...。看到No matching distribution直接查报错对照表第 1 行。
第 3 步：确认模块可导入。
python3 -c "import mediapipe as mp; print(mp.__version__)"通过信号：打印版本号，无 Traceback。
源码编译：仅定制或贡献需要
官方文档原话是"有本地改动才需要，否则强烈建议 pip install"（docs/getting_started/python.md）。Debian/Ubuntu 系统依赖照装，macOS 把 apt 换成brew install protobuf：
git clone --depth 1 https://gitcode.com/GitHub_Trending/med/mediapipe mediapipe cd mediapipe sudo apt install python3-dev python3-venv protobuf-compiler python3 -m venv mp_env && source mp_env/bin/activate pip install -r requirements.txt python3 setup.py install --link-opencv--link-opencv表示链接系统已装的 OpenCV；不带该参数则从源码构建 OpenCV（依据 setup.py）。
⚠️ 构建会临时改写 mediapipe/init.py 与 third_party/BUILD，生成
.backup文件并在结束自动还原（依据 setup.py）。若同一目录还要提交补丁，先确认已还原，或另开一份干净克隆。
验收：10 行脚本确认装好
测试图直接用仓库现成的 mediapipe/objc/testdata/sergey.png，拷到脚本同目录并命名sergey.png，cv2随 mediapipe 依赖自动装好：
import mediapipe as mp import cv2 img = cv2.cvtColor(cv2.imread("sergey.png"), cv2.COLOR_BGR2RGB) with mp.solutions.face_detection.FaceDetection() as fd: r = fd.process(img) print("OK: 检测到", len(r.detections), "张脸") if r.detections else print("NO_FACE")结果对照表：
| 运行输出 | 含义 | 下一步动作 |
|---|---|---|
OK: 检测到 1 张脸 | 安装成功 | 直接进"装完之后" |
NO_FACE | 模块正常，图里没检出脸 | 换一张含人脸的图重跑 |
ModuleNotFoundError: No module named 'mediapipe' | 装进了别的环境 | 核对 pip 与 python 是否同一解释器 |
报错对照表：5 条常见报错
报错原文、原因与修法均来自 docs/getting_started/troubleshooting.md：
| 报错关键词 | 原因 | 处理办法 |
|---|---|---|
ERROR: Could not find a version that satisfies the requirement mediapipe | PyPI 无匹配轮子，典型为 32 位 Python 或版本越界 | 改用 64 位 Python 3.9–3.14 并用pip --version确认；仍不行转源码编译 |
ERROR: An error occurred during the fetch of repository 'local_execution_config_python' | Bazel 找不到本地 Python | Bazel 命令追加--action_env PYTHON_BIN_PATH=$(which python3) |
error: undefined reference to 'cv::String::deallocate()' | OpenCV 未对 MediaPipe 配好 | OpenCV 4 按 docs/getting_started/install.md 改 third_party/opencv_linux.BUILD，按gcc -print-multiarch输出取消对应头文件行注释 |
ImportError: DLL load failed: The specified module could not be found | Windows 缺 VC++ 运行时 | 安装vc_redist.x64.exe，或用pip install msvc-runtime临时补上 |
ImportError: No module named numpy | 当前解释器缺 Python 依赖 | pip install -r requirements.txt |
装完之后
- docs/getting_started/python_framework.md：想在 Python 里搭自己的计算图的人读它。
- docs/getting_started/hello_world_cpp.md：C++ 桌面用户跑
bazel run验证环境，终端连续打印Hello World!即成功。 - docs/framework_concepts/calculators.md：准备加自定义 Calculator、走源码编译路线的人读它。
【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
