---

遇到 ModuleNotFoundError: No module named 'mediapipe' 是使用这个强大的计算机视觉库时的常见门槛。本文将从实际开发场景出发，手把手带你彻底解决这个问题。

错误发生的典型场景

这个错误通常出现在以下几种情况：

1. 全新环境：在新创建的Python环境或新机器上首次使用
2. 虚拟环境切换：从全局Python切换到虚拟环境时忘记安装
3. 版本冲突：其他依赖库与mediapipe的版本不兼容
4. 权限问题：在系统目录安装时缺少管理员权限

分平台安装指南

Windows系统

1. 基本安装（推荐使用Python 3.8+）：

pip install mediapipe

1. 使用conda环境（适合Anaconda用户）：

conda create -n mp_env python=3.8
conda activate mp_env
pip install mediapipe

macOS/Linux系统

1. 先安装系统依赖（以Ubuntu为例）：

sudo apt-get update && sudo apt-get install -y \
    python3-dev \
    python3-pip \
    protobuf-compiler

1. 常规安装：

python3 -m pip install --upgrade pip
pip install mediapipe

验证安装的正确姿势

使用这个带错误处理的脚本验证安装是否成功：

try:
    import mediapipe as mp
    print(f"成功导入MediaPipe {mp.__version__}")

    # 基础功能测试
    mp_hands = mp.solutions.hands
    print("关键模块加载正常")
except ModuleNotFoundError as e:
    print(f"导入失败: {e}")
    print("建议检查：")
    print("1. 是否在正确的Python环境下安装")
    print("2. 使用`pip list`查看已安装包")
except Exception as e:
    print(f"运行时错误: {e}")

生产环境部署指南

依赖管理进阶技巧

1. 生成依赖树（使用pipdeptree）：

pip install pipdeptree
pipdeptree | grep -i mediapipe

1. Dockerfile最佳实践：

FROM python:3.8-slim

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    protobuf-compiler \
    && rm -rf /var/lib/apt/lists/*

# 安装Python依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 版本锁定示例（requirements.txt）
# mediapipe==0.8.9.1
# opencv-python==4.5.5.64

常见避坑实践

1. Python版本问题：MediaPipe推荐使用Python 3.7-3.9
2. OpenCV依赖：如果遇到cv2相关错误，单独安装：

pip install opencv-python

1. 代理环境：使用国内镜像加速安装

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

验证与扩展

最后，分享一个快速验证脚本，检查所有关键功能是否正常：

import mediapipe as mp

def check_modules():
    required_modules = [
        'solutions.hands',
        'solutions.face_detection',
        'solutions.pose'
    ]

    for module in required_modules:
        try:
            __import__(f'mediapipe.{module}')
            print(f"✓ {module} 可用")
        except ImportError:
            print(f"✗ {module} 加载失败")

if __name__ == "__main__":
    print(f"MediaPipe 版本: {mp.__version__}")
    check_modules()

遇到问题时，建议查阅官方文档和GitHub issues。记住，90%的安装问题都可以通过创建干净的虚拟环境解决。Happy coding!