【MediaPipe】module 'mediapipe' has no attribute 'solutions' の原因と解決策

友人がハンドトラッキングをしようとしてMediaPipe+OpenCV+Pythonな環境を作ろうとしていた際、次のようなエラーが出てしまったのでそれを解決しようとしたものです。

module 'mediapipe' has no attribute 'solutions'

実行しようとしたプログラムを一部示します。「Mediapipe OpenCV Python」などで検索するとよく出てくる、典型的なコードです。

import cv2
import mediapipe as mp

mp_hands = mp.solutions.hands
hands = mp_hands.Hands()
mp_drawing = mp.solutions.drawing_utils

また友人はMacを使用していますが私はWindowsを使って今回の原因を探りました。
使用したバージョンは次の通りです。

• Host OS: Windows 11 Home (Version 25H2 / Build 26200)
• pip: pip 25.2
• uv: uv 0.9.8 (85c5d3228 2025-11-07)
  • Runtime: Python 3.12 (Managed by uv)

後述する解決策で特定のバージョン（v0.10.21など）のMediaPipeを使用する場合、Python 3.12を指定して環境構築を行いましょう。

問題の再現手順

モダンなパッケージマネージャーであるuvを使って、最新のライブラリをインストールしてみます。

> uv init test --python 3.12
> cd test
> uv add mediapipe opencv-python

標準の venv と pip を使用する場合は以下の通りです。

> python3.12 -m venv .venv

# 仮想環境のアクティベート（Mac / Linux / WSL の場合）
> source .venv/bin/activate

# 仮想環境のアクティベート（Windowsの場合）
> .venv\Scripts\activate.bat

# パッケージのインストール
> pip install mediapipe opencv-python

そして main.py にプログラムを書き込んで実行すると、冒頭のエラーが発生します。

解決策の検討

このエラーについて調査したところ、同じ問題を抱えている人は海外フォーラムなどに多数いましたが、日本語の文献はまだ少ないようでした。
結論から言うと、MediaPipe v0.10.30以降で、従来のmp.solutionsが完全に削除されたこと が原因 です。

We have removed support for MediaPipe Solutions. Please migrate to MediaPipe Tasks: https://ai.google.dev/edge/mediapipe/solutions/guide

出典：google-ai-edge/mediapipe - Issue #6192（schmidt-sebastian 氏の発言）

The Solutions API has been removed from MediaPipe version 0.10.30 onwards.

出典：google-ai-edge/mediapipe - Issue #6192（akashvverma1995 氏の発言）

The error AttributeError: module 'mediapipe' has no attribute 'solutions' occurs because the Legacy Solutions API (accessed via mp.solutions) was removed in MediaPipe version 0.10.31 and later, requiring a migration to the MediaPipe Tasks API

try using older version of mediapipe it will be fine.

出典：google-ai-edge/mediapipe - Issue #6261（mishbahul-hub 氏の発言）

つまり我々には以下の解決策があるということです。

1. 0.10.30よりも前のバージョンを使用する（本記事の対象）
2. MediaPipe Tasks API にコードを移行する（根本解決）

今回の友人のパターンではプログラムを動かせればよかったので1番を選びました。

解決策

ここでPythonの公式パッケージリポジトリであるmediapipe · PyPIのリリース履歴を確認してみました。すると0.10.30 の前の利用可能なバージョンは2025年2月7日の0.10.21 しかありませんでしたのでこれをインストールしていきます。

【uvを使用する場合】

> uv add mediapipe==0.10.21
Resolved 30 packages in 533ms
Installed 26 packages in 112ms
 + absl-py==2.4.0
 + attrs==26.1.0
 + ... (略)

【標準の pip を使用する場合】

> pip install mediapipe==0.10.21

これで再度スクリプトを実行したところ、無事にカメラが起動し、ハンドトラッキングを行うことができました。
この解決策を友人に伝えたところ、Mac（Apple Silicon環境）でも同様にダウングレードすることで無事に動作した とのことです。

Pythonのバージョンについて

このMediaPipe v0.10.21ですがCPythonでは3.11系か3.12系しかサポートしてないようです。
試しに次のように変更して実行してみましょう。

> uv python pin 3.13
Updated `.python-version` from `3.12` -> `3.13`

> uv run main.py
Using CPython 3.13.9
Removed virtual environment at: .venv
Creating virtual environment at: .venv
error: Distribution `mediapipe==0.10.21 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're using CPython 3.13 (`cp313`), but `mediapipe` (v0.10.21) only has wheels with the following Python ABI tags: `cp311`, `cp312`

このことから今回のv0.10.21では3.12の最新版を用いるのが良いでしょう。

最後に

今回は最新のMediaPipeでsolutionsというアトリビュートは無いと怒られる問題について考えてみました。
正直この記事の内容に大した新規性は無いかと思います。しかし日本語の記事の中には、かなり古いv0.10.14やv0.10.11を推奨しているものも見受けられたため今回記事にすることとしました。
ただし、バージョン固定はあくまで延命措置（技術的負債） です。 今後MediaPipeを本格的に利用していく場合は、早めに新しいTasks APIへの移行を検討した方がよさそうです。
今後この仕様変更に躓いた方の参考になれば幸いです。

参考文献

• mediapipe 0.10.31 for python does not contain mediapipe.solutions · Issue #6192 · google-ai-edge/mediapipe
• 'mediapipe' has no attribute 'solutions' · Issue #6261 · google-ai-edge/mediapipe
• AttributeError: module 'mediapipe' has no attribute 'solutions' · Issue #6200 · google-ai-edge/mediapipe
• Mediapipe error : r/PythonLearning
• AttributeError: module 'mediapipe' has no attribute 'solutions' : r/comfyui
• mediapipe · PyPI