2026年9月7日更新版本距离上次编辑时隔太久原版内容大幅过时借助AI核对最新资料之后刷新一下内容。现在 M1/M2/M3/M4 Mac 应该怎么装先确保 Terminal没有勾选“使用 Rosetta 打开”然后建议使用原生 Python。官方 MediaPipe 当前要求 Python 3.9、pip 20.3安装命令就是普通 pip。# 先确认当前终端/解释器是 ARM64 uname -m # 应输出 # arm64 python3 -c import platform; print(platform.machine()) # 建议项目单独建环境 python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install mediapipe验证python -c import mediapipe as mp, platform; print(mp.__version__); print(platform.machine())理想结果类似1.0.1 arm64当前 PyPI 的最新正式版是MediaPipe 1.0.12026 年 8 月 14 日发布并直接提供macosx_11_0_arm64包。M1 / Apple Silicon Mac 原生安装 MediaPipePython2026 更新版无需 Rosetta包含 PyCharm 配置与运行验证一、现在应该采用什么安装方案截至本次核对PyPI 列出的最新 MediaPipe 版本为1.0.1发布于 2026 年 8 月 14 日并提供原生 Apple Silicon 安装包mediapipe-1.0.1-py3-none-macosx_11_0_arm64.whl因此本教程采用的路线是原生终端 → 原生 Python → 项目虚拟环境 → pip 安装 → PyCharm 使用同一解释器。不再为这套环境开启 Rosetta也不需要专门安装 Intel 架构的 Python。Rosetta 用于运行 Intel 软件不是原生 MediaPipe 的安装前提。本教程使用以下配置项目本教程采用的配置处理器Apple SiliconPython 运行架构为arm64macOS下文 Homebrew 路线以macOS 14 或以上为前提Python原生Python 3.12MediaPipe固定安装1.0.1便于对照教程APIMediaPipe Tasks而不是旧mp.solutions这里有两个边界需要明确第一MediaPipe 的最低系统标记不等于 Homebrew 的支持范围。上述 wheel 标记为 macOS 11.0 ARM64但 Homebrew 当前受支持的 macOS 安装要求是 macOS 14。旧系统不能仅凭 MediaPipe 的文件名就直接套用整套 Homebrew 安装流程。第二Python 3.12 是本文选用的教程基线不是唯一支持版本。官方设置页目前写的是 Python 3.9 及以上、pip 20.3 及以上PyPI classifiers 明列 Python 3.9–3.12。不能据此断言更新的 Python 一定不支持也不能认为所有更新版本都已经完整验证。二、准备原生终端和 Python1. 不使用 Rosetta 启动这次安装所用的终端此前按照旧教程勾选过“使用 Rosetta 打开”的先取消勾选再彻底退出并重新打开终端。该选项会让支持它的通用应用以 Intel 模式运行。执行uname -m本教程需要看到arm64注意终端是 ARM64不代表你调用的 Python 也一定是 ARM64。后面还要单独检查 Python 解释器。2. 准备原生 HomebrewApple Silicon 上 Homebrew 的默认安装前缀是/opt/homebrewIntel Homebrew 的默认前缀则是/usr/local。不要直接照抄旧教程里的/usr/local/homebrew/...路径。已经存在/opt/homebrew/bin/brew时不必重复安装。尚未安装时在原生终端执行官方安装命令并根据提示准备所需的命令行工具/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装后按照安装器显示的Next steps配置 shell。对当前终端会话可以执行eval $(/opt/homebrew/bin/brew shellenv) /opt/homebrew/bin/brew --prefix默认原生安装应输出/opt/homebrew永久配置以安装器给出的步骤为准。3. 安装指定版本的 Python下面明确调用原生 Homebrew避免误用电脑上另一套 Intel Homebrew/opt/homebrew/bin/brew install python3.12 /opt/homebrew/bin/python3.12 --version /opt/homebrew/bin/python3.12 -c import platform; print(platform.machine())应分别看到Python 3.12.x arm64Homebrew 的这个 formula 将版本化解释器安装到$HOMEBREW_PREFIX/bin/python3.12因此这里不依赖python3恰好指向哪个版本。已有其他来源的原生 Python 3.12 时可以跳过 Homebrew后续创建环境时使用已经确认过的解释器路径。三、创建并激活项目虚拟环境使用新项目目录不要直接复用以前由 Intel Python 创建的虚拟环境。虚拟环境依赖创建它的基础解释器不是可以随意搬动或跨环境复用的文件夹。mkdir -p ~/Projects/mediapipe-demo-2026 cd ~/Projects/mediapipe-demo-2026 /opt/homebrew/bin/python3.12 -m venv .venv source .venv/bin/activate这个目录中已经有旧.venv的请另选一个新项目目录而不是覆盖重用。检查当前解释器、架构以及是否处于虚拟环境python -c import sys, platform; print(sys.executable); print(platform.machine()); print(sys.prefix ! sys.base_prefix)应看到类似结果/Users/你的用户名/Projects/mediapipe-demo-2026/.venv/bin/python arm64 True其中sys.prefix ! sys.base_prefix为True表示当前解释器运行于虚拟环境。若不是先修正环境选择不要继续向基础 Python 安装项目依赖。四、安装并验证 MediaPipe确认已经进入虚拟环境后执行python -m pip install --upgrade pip python -m pip install mediapipe1.0.1 python -m pip check这里采用官方的python -m pip安装方式并固定 MediaPipe 版本以便对照本文。python -m pip能明确让安装操作对应当前 Python减少“包装在一个环境脚本却在另一个环境运行”的问题。pip check成功时通常输出No broken requirements found.它检查的是已安装包声明的依赖关系不会替你运行模型。继续验证导入python - PY import sys import platform import mediapipe as mp from mediapipe.tasks.python import vision print(Python:, sys.version.split()[0]) print(解释器:, sys.executable) print(架构:, platform.machine()) print(MediaPipe:, mp.__version__) print(HandLandmarker:, vision.HandLandmarker.__name__) PY关键结果应包括架构: arm64 MediaPipe: 1.0.1 HandLandmarker: HandLandmarker这里使用的是官方当前的 Tasks 导入路径。到这一步验证的是“安装与导入”完整的模型加载与推理在第六节验证。五、在 PyCharm 中使用同一个环境用 PyCharm 打开刚创建的mediapipe-demo-2026项目进入Settings → Python → Interpreter → Add Interpreter → Add Local Interpreter选择已有 Python 解释器定位到/Users/你的用户名/Projects/mediapipe-demo-2026/.venv/bin/python当前 PyCharm 文档对已有虚拟环境的处理方式就是选择其 Python 可执行文件并复用该环境。菜单名称可能随版本和界面语言略有不同但关键始终是选择项目的.venv/bin/python不要重新创建一个空环境也不要随手选中基础 Python。在 PyCharm 的 Python Console 或脚本中检查import sys import platform import mediapipe as mp print(sys.executable) print(platform.machine()) print(mp.__version__)将结果与终端中的输出比较。若解释器路径不同先修正解释器设置不要把“重新安装一遍 MediaPipe”作为第一步。六、使用 Tasks API 跑一次图片检测1. 旧代码需要迁移不只是重装包旧教程常见的mp.solutions.hands mp.solutions.pose mp.solutions.face_mesh不能直接套到本文版本。项目维护者明确说明Solutions API 从 MediaPipe 0.10.30 起移除应迁移到 MediaPipe Tasks。因此缺少solutions属性不是“M1 不受支持”也不能靠开启 Rosetta 修复。下面以 Hand Landmarker 为例。这个任务需要对应的模型文件仅安装 Python 包并不等于已经准备好模型。2. 下载模型在项目根目录执行。该固定版本模型地址也用于 Google 官方示例mkdir -p models curl -fL --retry 3 \ https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task \ -o models/hand_landmarker.task模型下载是独立的网络步骤。下载失败时应先解决下载问题而不是重装 Python。3. 准备图片和检测脚本将一张包含清晰手部的 JPG 图片放到项目根目录命名为hand.jpg。目录结构如下mediapipe-demo-2026/ ├── .venv/ ├── models/ │ └── hand_landmarker.task ├── hand.jpg └── check_hand.py创建check_hand.py。以下示例按照官方 Python API使用图片模式创建任务、读取图片并执行检测from pathlib import Path import mediapipe as mp from mediapipe.tasks import python as mp_python from mediapipe.tasks.python import vision def main() - None: # 相对于脚本定位文件避免 PyCharm 工作目录不同导致路径错误。 root Path(__file__).resolve().parent model_path root / models / hand_landmarker.task image_path root / hand.jpg for label, path in ((模型, model_path), (图片, image_path)): if not path.is_file(): raise FileNotFoundError(f找不到{label}文件{path}) options vision.HandLandmarkerOptions( base_optionsmp_python.BaseOptions( model_asset_pathstr(model_path) ), running_modevision.RunningMode.IMAGE, num_hands2, ) image mp.Image.create_from_file(str(image_path)) with vision.HandLandmarker.create_from_options(options) as landmarker: result landmarker.detect(image) print(f检测到 {len(result.hand_landmarks)} 只手) for index, landmarks in enumerate(result.hand_landmarks, start1): print(f第 {index} 只手{len(landmarks)} 个关键点) if __name__ __main__: main()运行python check_hand.py成功检测时每只手应得到21 个关键点。程序正常结束但检测数量为0表示这张图片没有产生达到阈值的检测结果不能单凭这一点判断安装失败。本示例只输出数量不生成标注图片。实际运行成功后才能说明这台机器上的“解释器 → Python 包 → 模型加载 → 单次推理”流程已经走通。七、常见错误与处理顺序现象优先处理方式No matching distribution found检查 Python 实际架构、版本、pip 兼容标签和使用的包索引不要直接归因于“M1 不支持”。externally-managed-environment回到项目虚拟环境安装不要继续修改 Homebrew 的基础 Python。终端能导入PyCharm 不能比较两边的sys.executable确认选中了同一个.venv。module mediapipe has no attribute solutions本文版本使用 Tasks API旧程序需要迁移。模型文件找不到核对models/hand_landmarker.task的位置以及传给model_asset_path的路径。出现安装候选不匹配时可先收集以下信息python --version python -c import sys, platform; print(sys.executable); print(platform.machine()) python -m pip --version python -m pip debug --verboseHomebrew 官方建议在虚拟环境中安装项目依赖。不要把sudo pip install或--break-system-packages当作这份教程的正常安装步骤。本版的核心变化安装走原生 ARM64 路线PyCharm 复用项目环境程序使用 Tasks API并把“安装成功”和“推理成功”分开验证。旧文发现Windows上只需要一行的pip3 install mediapipe就能搞定的安装到arm chip的Macbook 上变得异常复杂网上资料很少几乎没有中文教程·参考了StackOverFlow-cannot-pip-install-mediapipe-on-macos-m1https://stackoverflow.com/questions/68659865/cannot-pip-install-mediapipe-on-macos-m1的资料跑通了安装过程。所以抛砖引玉半原创半翻译写一篇教程。下面让我来介绍一下我的优化后的方法希望可以帮到你第一步在 访达(Finder) 中启用Rosetta打开访达搜索Terminal看见“终端”的图标之后鼠标右击图标点选“显示简介”如下图勾选“使用Rosetta打开”第二步 关闭原来的终端新建一个Terminal窗口Command (⌘)-空格键输入terminal按下回车键。第三步 安装HomeBrew/bin/zsh -c $(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)⬆️根据大佬的提示选择下载源操作即可⬆️第四步 安装非Arm架构的pythonarch -x86_64 /usr/local/homebrew/bin/brew install python3.10第五步 创建一个新的虚拟环境arch -x86_64 /usr/local/homebrew/opt/python3.10/bin/python3 -m venv myvenv第六步 启动虚拟环境source ~/myvenv/bin/activate第七步 安装mediapipepip3 install mediapipe -i https://pypi.tuna.tsinghua.edu.cn/simpleok啦大功告成python3import mediapipe如果没有报错那么恭喜你成功安装了mediapipe.如果想要继续配置pycharm在pycharm里面使用mediapipe请继续往下看注安装的是m1版本的社区版pycharm第八步 选择interpreter在PyCharm中新建project的时候在interpreter一栏目根据安装地址点击右侧(···)选择 /usr/local/homebrew/opt/python3.10/bin/python3第九步 安装mediapipe在pycharm底部点击Terminal输入如下命令pip3 install mediapipe -i https://pypi.tuna.tsinghua.edu.cn/simpleover了这是我的第一篇技术博客欢迎大家留言交流呀