MediaPipe Python 安装指南：3步装完跑通人脸检测，真正需要时才从源码编译
项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe MediaPipe 是面向媒体处理的跨平台实时机器学习框架，人脸关键点、手势、姿态都只要几行代码。这篇文章带你装好 Python 版：先用 pip 三步装完并跑通第一个人脸检测案例，只有在需要定制时才进入源码编译分支，坑和解法一并给到。
先判断：你大概率不需要编译 🚦
结论放前面：90% 的场景直接用 PyPI 上的预编译包就够了。
MediaPipe 的 Python 包在 PyPI 上已经打包好了 Linux（x86_64）、macOS、Windows（amd64）三个平台的二进制，装完就能 import。只有下面三种情况才值得走源码编译：
- 你要改源码：新增自定义 calculator、修一个上游 bug、给团队打包定制 wheel
- 你的平台是 aarch64 Linux（Nvidia Jetson、树莓派）：PyPI 没有这个架构的 wheel，只能自己编译
- 你需要离线交付一个可控版本的安装包
如果你不在这三种情况里，直接跳到下一节的主路径，别碰编译。
MediaPipe 能做的事情远不止人脸：上图为 3D 物体跟踪（Objectron）效果
主路径：pip 三步装好 MediaPipe 📦
第一步：确认环境
你需要 64 位的 Python 3.9 ~ 3.12。一行命令确认：
python3 --version
版本不在范围内时先升级 Python，后面所有步骤都依赖它。
第二步：建虚拟环境并安装
python3 -m venv mp_env && source mp_env/bin/activate
pip install mediapipe
第一条命令创建并激活一个叫 mp_env 的隔离环境（不污染系统 Python）；第二条安装 MediaPipe 及其全部依赖（numpy、opencv-contrib-python、absl-py 等，清单见仓库根目录的 requirements.txt）。
第三步：验证
import mediapipe as mp
print(mp.__version__)
能打印出版本号、不报 ImportError，安装就完成了。以后退出环境用 deactivate。
第一个完整案例：给照片画上人脸检测 🧪
安装成功不等于会用。跑一个最小的人脸检测案例，顺便记住一个最容易踩的坑：MediaPipe 吃 RGB，OpenCV 读出来是 BGR，必须转换，否则识别率会莫名变差。
import cv2
import mediapipe as mp
image = cv2.imread("your_photo.jpg") # 换成你自己的照片
rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
with mp.solutions.face_detection.FaceDetection(
model_selection=1, min_detection_confidence=0.5) as detector:
result = detector.process(rgb)
for face in result.face_landmarks:
for p in face.landmark: # 每张脸 6 个关键点
cv2.circle(image, (int(p.x * image.shape[1]),
int(p.y * image.shape[0])), 2, (0, 255, 0), -1)
cv2.imwrite("detected.jpg", image)
model_selection=1 选择通用人脸模型（适合远距离、正脸偏多的照片）；min_detection_confidence=0.5 是置信度门槛。各参数含义可以查 docs/getting_started/python.md 里的 Face Detection 章节。
上图就是这类输出：检测框、6 个关键点（眼、鼻、嘴）和置信度分数
分支：源码编译什么时候上、怎么上 🔧
只有前面说过的那三种情况才走这里。核心是三个工具链：Bazel（3.4.0 及以上，setup.py 里有硬检查，版本过旧会直接报错退出）、OpenCV、Protobuf 编译器。
Debian / Ubuntu 一条命令装依赖：
sudo apt install python3-dev python3-venv protobuf-compiler
macOS 用 brew install protobuf（需要源码编译 OpenCV 时再加 cmake）。OpenCV 本身用系统包管理器装好即可，不必自己编。
然后是克隆、装依赖、编译：
git clone https://gitcode.com/GitHub_Trending/med/mediapipe
cd mediapipe
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 的几十分钟；不加则走 Bazel 静态编译 OpenCV，更慢但环境更干净。日常用建议加。- 想打 wheel 而不是直接装：把最后一条换成
python3 setup.py bdist_wheel，产物在dist/下，pip install dist/mediapipe-*.whl即可。
还有一个不显眼但真实的坑：setup.py 里 MEDIAPIPE_DISABLE_GPU 环境变量默认值是关闭 GPU 编译的。如果你要一个带 GPU 支持的自编译包，编译前先 export MEDIAPIPE_DISABLE_GPU=0。
三个最常见的坑，和解法 🩹
Bazel 找不到 Python 路径
报错里带 local_execution_config_python 和 Repository command failed 字样，意思是 Bazel 没定位到你的 Python 解释器。给构建命令补一个环境变量即可：
bazel build --action_env PYTHON_BIN_PATH=$(which python3) ...
链接 OpenCV 4 报 undefined reference
系统的 OpenCV 4（Debian 11 / Ubuntu 21.04 起常见）和仓库默认构建配置不匹配。解法是编辑 third_party/opencv_linux.BUILD 里的 cc_library，把 hdrs = glob(["include/opencv4/opencv2/**/*.h*"]) 和 includes = ["include/opencv4/"] 两行加上（多架构系统按 gcc -print-multiarch 的结果换成对应子目录）。
aarch64 装不上，报"找不到匹配的 wheel"
这不是错误，是"缺失"：PyPI 官方不提供 aarch64 的 wheel。Jetson、树莓派用户没有捷径，只能按上一节自己编译，耗时以小时计。建议预留时间，并且把机器上的 OpenCV 也一并装齐再动手。
装完之后往哪走
- Python 框架与 Solutions 用法总览：docs/getting_started/python.md
- 源码编译各平台环境搭建：docs/getting_started/install.md
- 常见构建错误全集：docs/getting_started/troubleshooting.md
- 各方案（Face Mesh、Hands、Pose 等）细节：docs/solutions/
- 各平台运行示例：mediapipe/examples/
记住一条主线：先用 pip 跑通，能跑就不要编译；要编译就带着 --link-opencv 和 PYTHON_BIN_PATH 上工，能省掉大部分折腾。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
