はじめに

Windows 11 環境で Python を使い、画像処理の検証を進めていた。
OpenCV が必要になり、いつも通り pip install opencv-python を実行したところ、見慣れないエラーにぶつかった。

Linux（Mint や EndeavourOS）では問題なく動いていたため、正直なところ最初は戸惑った。
本記事では、実際に自分が遭遇したエラー内容と、原因を切り分けながら解決に至った過程を整理する。

同じ状況で立ち止まっている人の助けになれば幸いだ。

---

発生した環境とエラー内容

まず、当時の環境は以下の通りだ。

• OS：Windows 11
• Python：3.14.0
• pip：25.3
• numpy：2.3.4

この状態で pip install opencv-python を実行すると、次のようなエラーが出た。

Preparing metadata (pyproject.toml) ... error
error: subprocess-exited-with-error

× Encountered error while generating package metadata.
╰─> numpy

note: This is an issue with the package mentioned above, not pip.

pip 自体は PATH に通っており、他のライブラリは普通にインストールできている。
「pip の問題ではない」と言われても、では何が悪いのか分からない。
ここが最初の当惑ポイントだった。

---

切り分けのために考えたこと

エラーメッセージを冷静に眺めると、いくつか気になる点があった。

• wheel をビルドしようとしている
• エラーの原因として numpy が名指しされている
• Linux では同じ構成で問題が出ていない

ここから「Windows 固有の問題」か「Python バージョン起因」のどちらかだろうと当たりをつけた。

さらに調べていくと、opencv-python が依存している numpy のバージョンに制約があることが分かった。

---

問題の本質：Python 3.14 が早すぎた

結論から言うと、原因は Python 3.14 を使っていたこと だった。

• opencv-python は numpy 2.3 未満に依存している
• numpy 2.2.x は Python 3.14 に対応していない
• numpy 2.3.x は Python 3.14 に対応しているが、opencv-python が未対応

つまりこういうことだ。

Python 3.14 → numpy 2.3 しか入らない
opencv-python → numpy 2.2 系を要求
結果として依存関係が成立しない

pip のエラーは分かりにくいが、内部ではこの依存関係の矛盾で止まっていた。

---

実際に取った解決策

対応は驚くほどシンプルだった。

• Python 3.14 をやめる
• Python 3.13 をインストールする

Python 3.13 環境を用意し、同じコマンドを実行すると、あっさり成功した。

pip install opencv-python

エラーなし。
拍子抜けするほどあっさりだ。

---

なぜLinuxでは動いていたのか

ここで一つ腑に落ちた点がある。

Linux 側では Python 3.12 系を使っていた。
つまり、最初から opencv-python と numpy の依存関係が成立する環境だったわけだ。

Windows と Linux の違いではなく、「Python のバージョン差」が原因だった。

---

まとめ

今回の学びは次の通りだ。

• 最新の Python が必ずしも最適とは限らない
• C/C++ 拡張を含むライブラリは対応バージョンに要注意
• pip の subprocess-exited-with-error は依存関係エラーを疑う

特に opencv-python のような定番ライブラリでも、新しい Python への対応は遅れることがある。
実務や検証で使うなら、一つ前の安定版 Python を選ぶのが無難だと改めて感じた。

同じエラーで詰まっているなら、まず Python のバージョンを疑ってみてほしい。
それだけで、時間を無駄にせずに済む。