Windows安装mediapipe

Windows 安装 MediAPIpe：从环境准备到可运行示例，一次讲清

问题分析

MediaPipe 是 Google 开源的跨平台视觉与音频处理框架，常用于手势识别、人体姿态、脸部关键点、目标检测等场景。Windows 上安装它，最常见的问题不是“装不上”，而是“装上了但跑不起来”。原因通常集中在这几类：

Python 版本不匹配。
pip 太旧或装到了错误的环境里。
缺少 protobuf、opencv 等依赖，或者版本冲突。
32 位 Python 和 64 位包不兼容。
公司网络、代理、镜像源配置不当，导致下载失败。

如果你的目标是让 MediaPipe 在 Windows 里稳定可用，最稳妥的思路是先把 Python 环境收干净，再按兼容版本安装，不要一上来就乱升级依赖。

解决方案

一、先准备正确的系统环境

MediaPipe 在 Windows 上建议直接使用 64 位 Python，并优先选用常见稳定版本。实际使用里，最省事的组合通常是：

Windows 10 / Windows 11 64 位
Python 3.10 或 3.11
pip、setuptools、wheel 更新到较新版本
使用虚拟环境隔离项目

先检查你的 Python 是否可用。在命令提示符或 PowerShell 里执行：

python --version
pip --version

如果系统里有多个 Python，建议用：

py -0p

它会列出当前系统安装的 Python 路径，方便你确认到底用的是哪一个。

如果还没装 Python，建议直接去 Python 官方安装包安装 64 位版本，安装时勾选：

Add python.exe to PATH
Install launcher for all users

这样后面命令行会省很多麻烦。

二、创建独立虚拟环境

不要直接往系统全局环境里装。MediaPipe 这类库依赖比较多，最容易被别的软件污染。推荐先建一个虚拟环境：

python -m venv mediapipe_env
mediapipe_env\Scripts\activate

激活成功后，命令行前面一般会出现环境名，比如：

(mediapipe_env)

然后先升级基础工具：

python -m pip install --upgrade pip setuptools wheel

这一步很关键，很多安装失败就是因为旧版 pip 解析不了新包。

三、安装 MediaPipe

直接执行：

pip install mediapipe

如果网络慢，可以换国内镜像源，例如清华源：

pip install mediapipe -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你是做图像处理项目，通常还会一起装 opencv-python：

pip install opencv-python

基础组合一般就够了。很多人一上来就手动装一堆依赖，结果把版本关系搞乱，反而更难排查。

四、做一个最小测试，确认安装成功

安装后不要直接开始做复杂项目，先跑一个最简单的版本确认环境正常。可以测试导入：

import mediapipe as mp
print(mp.__version__)

如果没有报错，说明基本安装成功。

你也可以继续测 OpenCV：

import cv2
print(cv2.__version__)

如果这两个都能正常输出版本号，说明 Python 环境、依赖和包基本都没问题。

五、一个适合新手的手势识别测试示例

下面这个示例可以快速验证摄像头、MediaPipe 和 OpenCV 是否同时正常工作：

import cv2
import mediapipe as mp

mp_hands = mp.solutions.hands
hands = mp_hands.Hands(
    static_image_mode=False,
    max_num_hands=2,
    min_detection_confidence=0.5,
    min_tracking_confidence=0.5
)
mp_draw = mp.solutions.drawing_utils

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break

    frame = cv2.flip(frame, 1)
    rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
    result = hands.process(rgb)

    if result.multi_hand_landmarks:
        for hand_landmarks in result.multi_hand_landmarks:
            mp_draw.draw_landmarks(frame, hand_landmarks, mp_hands.HAND_CONNECTIONS)

    cv2.imshow("MediaPipe Hands", frame)

    if cv2.waitKey(1) & 0xFF == 27:
        break

cap.release()
cv2.destroyAllWindows()

运行后如果能看到摄像头画面，并且手部关键点会跟着动，就说明安装和调用都成功了。

注意事项

不要混用多个 Python 环境。

很多报错看起来像安装失败，其实是你装到 A 环境，运行时却在用 B 环境。

不要盲目升级所有依赖。

尤其是 protobuf、numpy、opencv-python，版本乱升以后，经常出现导入报错。

如果提示找不到 mediapipe，先检查解释器。

可以执行：

```bash

where python

where pip

```

看看是不是当前命令行用的不是你装包时的那个环境。

如果摄像头打不开，不一定是 MediaPipe 的问题。

先测试：

```python

import cv2

cap = cv2.VideoCapture(0)

ret, frame = cap.read()

print(ret)

```

如果这里就是 False，优先排查摄像头权限、驱动、占用情况。

企业网络或代理环境下，安装失败很常见。

这时建议优先配置稳定镜像源，或者手动下载轮子包安装。

常见报错处理

1. No module named mediapipe

说明当前解释器里没有装成功，或者装到了别的环境。重新激活虚拟环境后再执行：

pip install mediapipe

2. Could not find a version that satisfies the requirement mediapipe

通常是 Python 版本不匹配，或者位数不对。优先确认：

python --version

以及是不是 64 位 Python。旧版本 Python 很容易装不上。

3. ImportError 或 DLL load failed

多半是依赖冲突，先更新基础工具，再重装：

python -m pip install --upgrade pip setuptools wheel
pip uninstall mediapipe -y
pip install mediapipe

如果还不行，建议新建一个干净虚拟环境重新装，不要在已经污染的环境里硬修。

4. 摄像头黑屏或无画面

先检查摄像头权限、是否被微信、QQ、会议软件占用，再确认 VideoCapture(0) 的索引是否正确。有些笔记本内置摄像头不是 0，可能要试 1 或 2。

进阶建议

如果你后面要长期做 MediaPipe 开发，建议这样组织环境：

一个项目一个虚拟环境。
用 requirements.txt 固定依赖版本。
不在系统 Python 里直接装一堆包。
大项目建议配合 VS Code 或 PyCharm 管理解释器。

requirements.txt 可以这样写：

mediapipe
opencv-python

安装时执行：

pip install -r requirements.txt

这样以后迁移到另一台 Windows 电脑会更省事。

总结

在 Windows 上安装 MediaPipe，核心不是“复杂”，而是“环境要干净，版本要对，顺序要稳”。最推荐的做法是：安装 64 位 Python，创建虚拟环境，升级 pip 后直接安装 mediapipe 和 opencv-python，再用最小示例验证。只要环境没乱，MediaPipe 在 Windows 上其实很容易跑起来。