解决MediaPipe Python 3.7兼容难题：从报错到完美运行

2026-02-04 05:19:13作者：范垣楠Rhoda

你是否在Python 3.7环境下安装MediaPipe时遇到各种报错？从依赖冲突到语法错误，本文将帮你一一解决，让MediaPipe在Python 3.7上完美运行。读完本文，你将了解兼容性问题的根源，掌握修改依赖版本和源码的方法，以及如何验证安装结果。

问题现象：Python 3.7环境下的常见报错

在Python 3.7环境中安装或运行MediaPipe时，用户通常会遇到以下几类错误：

1. 安装时的依赖冲突

ERROR: Could not find a version that satisfies the requirement protobuf>=4.25.3,<5 (from mediapipe)
ERROR: No matching distribution found for protobuf>=4.25.3,<5

2. 运行时的语法错误

  File "mediapipe/python/solution_base.py", line 123
    if self._graph is None:
    ^
SyntaxError: invalid syntax

3. 导入模块失败

ImportError: cannot import name 'Packet' from 'mediapipe.python.packet'

这些问题主要源于MediaPipe官方已不再支持Python 3.7，但其核心功能经过适当调整仍可在该环境下运行。

问题根源：版本限制与依赖要求

官方支持的Python版本

查看MediaPipe的setup.py文件，在classifiers部分可以看到官方明确支持的Python版本：

classifiers=[
    # ...
    'Programming Language :: Python :: 3.9',
    'Programming Language :: Python :: 3.10',
    'Programming Language :: Python :: 3.11',
    'Programming Language :: Python :: 3.12',
    # ...
],

Python 3.7并未出现在支持列表中，这是兼容性问题的根本原因。

依赖库版本要求

MediaPipe的requirements.txt中指定了多个依赖库的版本要求：

absl-py
attrs>=19.1.0
flatbuffers>=2.0
protobuf>=4.25.3,<5
# ...

其中protobuf 4.25.3及以上版本已不再支持Python 3.7，这是导致安装失败的主要依赖冲突。

解决方案：三步实现Python 3.7兼容

步骤一：修改依赖版本

创建一个适用于Python 3.7的requirements.txt文件，降低冲突依赖的版本：

absl-py==0.15.0
attrs>=19.1.0
flatbuffers>=2.0
protobuf==3.20.1
numpy<2
opencv-contrib-python
# 其他依赖保持不变

关键是将protobuf降级到3.20.1版本，这是支持Python 3.7的最新protobuf版本。

步骤二：调整setup.py中的版本限制

修改setup.py文件，在classifiers中添加Python 3.7支持：

classifiers=[
    # ...
    'Programming Language :: Python :: 3.7',
    'Programming Language :: Python :: 3.9',
    # ...
],

同时修改python_requires参数：

python_requires='>=3.7',

步骤三：修复语法兼容性问题

MediaPipe的部分Python代码使用了Python 3.8+的语法特性，需要进行修改。例如，在mediapipe/python/solution_base.py中可能存在海象运算符(:=)的使用，需要替换为传统的if-else结构。

验证步骤：测试MediaPipe功能

完成上述修改后，通过以下步骤验证安装是否成功：

1. 安装修改后的MediaPipe

pip install -r requirements.txt
pip install .

2. 运行手部追踪示例

import cv2
import mediapipe as mp

mp_hands = mp.solutions.hands
hands = mp_hands.Hands()
cap = cv2.VideoCapture(0)

while cap.isOpened():
    success, image = cap.read()
    if not success:
        continue
        
    results = hands.process(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
    
    if results.multi_hand_landmarks:
        for hand_landmarks in results.multi_hand_landmarks:
            mp.solutions.drawing_utils.draw_landmarks(
                image, hand_landmarks, mp_hands.HAND_CONNECTIONS)
    
    cv2.imshow('MediaPipe Hands', cv2.flip(image, 1))
    if cv2.waitKey(5) & 0xFF == 27:
        break

hands.close()
cap.release()