opencv-python をインストールできないとき【Raspberry Pi】

Raspberry Pi に OpenCV (opencv-python)をインストールできないときの対処方法についてまとめておきます。

以下の環境で動作確認をしています。
・　Raspberry Pi (bullseye)
・　Python 3.9.2
※　以下は Raspberry Pi (Linux) の事例で記載していますが、Windows など他の環境でも、同じ考え方で対処できるように思います。

背景～バージョンアップが頻繁すぎる …

Raspberry Pi で起動用 SDカードを作ると、よく使われる Python や NumPy、pygame、tkinter、i2c-tools などが標準で入っています。

しかし、標準では OpenCV は入っていません。カメラ、画像処理、機械学習を扱いたいとなると、OpenCV が必要となってきます。そこで、自分でインストールを行うことになります。
ところが、最新バージョンの起動用 SD カードを作って Python 版の OpenCV をインストールしようとすると、いずれかのプログラムがアップデートされており、エラーが出て動かないといったことが、しばしば起こります。

ということで、OpenCV のインストールに関し、過去に経験したエラー、対処の方針、具体例を類型化し、公開しておくことにします。

OpenCV をインストールする手順

OpenCV のインストールは、標準的には、以下の２段階が必要です。
[1]　OpenCV を動かすのに必要な関連ライブラリのインストール
[2]　OpenCV 本体（opencv-python）のインストール（pip install opencv-python）
詳細は、「初期設定のまとめ【OpenCV & Raspberry Pi】」（後半部分）にまとめていますので参照してください。

OpenCV のインストール時のエラーの類型化

正常に動くかどうかを確認する手順

上記の手順でインストールをし、OpenCV のスクリプト等がそのまま動いた場合は、とくに問題はありません。
一例として以下に、ターミナルから Python を起動し、OpenCV のパッケージを読み込んでみるコマンドの例を挙げておきます。（★１）

$ python
Python 3.9.2 (default, Mar 12 2021, 04:06:34)
[GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import cv2
>>> exit()

※　エラー表示が出ることなく、（★１）がうまく動いたときは、OpenCV を使ったサンプルスクリプト（★２）なども動かしてみてください。（★２）まで動けば、正常にインストールできています。
OpenCV のサンプルスクリプトの例を、末尾の関連リンクに挙げておきます。必要があれば参照してみてください。

エラーが出たとき　～現象を類型化してみる

ところが、各プログラムのバージョンアップが頻繁で、ずっと続いています。
知らないうちにバージョンアップが進み、最新バージョンの組み合わせによっては動かなくなることがよくあります。

インストールがうまくできず動かない状況については、経験的に、以下でパターン分けできそうです。
[A]　opencv-python のインストール自体ができない。
具体的には、以下のような場合です。
・　インストールのコマンドを実行するとエラー表示が出て、インストールが開始できない。
・　インストールは開始するものの、途中で止まってしまい、動かなくなる。
[B]　opencv-python のインストールは完了する。しかし、Python で OpenCV をインポートすると、または、Python のスクリプトで OpenCV を実行しようとするとエラーが出る。
具体的には、以下のような場合です。
・　import cv2 と記載した Python のスクリプトを実行すると、”… cv2 … ” 等といったエラー表示が出る。
・　Python のスクリプトを実行すると、”… numpy …” 等といったエラー表示が出る。

エラーが起きたときの対処方針

上記のエラー表示から、Python、opencv-python、numpy あたりが関係していると考えられます。
そこで、ネット検索をすると、過去の旧バージョンの組み合わせでは動いている事例が見つかります。
このことから原因は、バージョンの新旧の組み合わせが対応していないことにあると推測できます。

したがって、OpenCV を動かすための対処方針としては以下となります。
方針： Python、opencv-python、numpy など、関係しているプログラムのバージョンを指定・確認しつつ、動く組み合わせを探す。
環境によっては、試行錯誤が生じることになります。

対処手順

ステップ１：自分の環境（Linux、Python のバージョン）を確認する

まず、下記のコマンドを実行し、Raspberry Pi の OS （Linux）のバージョンを確認しておきます。

$ lsb_release -a
Release: 11
Codename: bullseye

つぎに、Python のバージョンについても確認をしておきます。

$ python3 --version 
Python 3.9.2

※　ネット検索をして、自分と同じ OS 環境や Python のバージョンで OpenCV が動いた事例が見つかるのであれば、バージョンの組み合わせが同等となるよう設定すれば、動くであろうと考えられます。
※　また、あらたに、Raspberry Pi の起動用SDカードを作成したとき、Python など主要なプログラムがアップデートされていると、バージョンに関する情報がネット上では見つけづらくなります。
この場合は情報がないので、トライ＆エラーで動くバージョンの組み合わせを探すことになります。

ステップ２： opencv-python のバージョンを指定してインストールする

opencv-python のバージョンを指定してインストールするコマンドの例は、以下のとおりです。

$ pip install opencv-python==3.4.18.65

※　私の環境では、Python 3.9.2 の場合、上記のコマンドで opencv-python のインストールが正常に完了しました。（これより新しくすると、Raspberry Pi の環境では、エラーが出るようです。）
この後、上記の（★１）、（★２）を実行し、OpenCV がうまく動けば、インストールから動作確認まで完了です。
※　インストールが失敗する場合は、上記のコマンドの末尾部分のバージョンを新旧変えて、インストールがうまく完了するバージョンを探してください。インストールがうまくできたら、（★１）、（★２）を確認してください。
※　インストールが可能な opencv-python のバージョンを確認するには、”pip install opencv-python==-1″ を実行すると表示されると思います。（存在しないバージョンを指定する。）
※　opencv-python のインストールまで完了したけれども、（★１）、（★２）で、”numpy” 関連のエラーが表示される場合は、ステップ３に進んでください。

ステップ３： NumPy のバージョンを指定してインストールする

Python のスクリプトなどで import cv2 等を実行して、”… numpy … ” 等のエラー表示がされる場合は、NumPy のバージョンを新旧変えてインストールをしてみてください。
NumPy のバージョンを指定してインストールをするコマンドの例は、以下のとおりです。

$ pip install numpy==1.24.0

※　私の環境では、Python 3.9.2、opencv-python 3.4.18.65 とした場合、上記のコマンドで NumPy のバージョンを 1.24.0 と指定したところ、うまく OpenCV が動くようになりました。（NumPy を最新バージョンにするとエラーが出る。）
※　インストールが可能な NumPy のバージョンを確認するには、”pip install numpy==-1” を実行してみてください。（存在しないバージョンを指定する。）

※　なお、OpenCV の仕様として、Python のスクリプト内で OpenCV をインポートすると、自動的に NumPy もインポートされます。
つまり、Python で import cv2 を実行すると、import numpy を実行しなくても、NumPy を使用できるという依存関係となっています。
ところが、Raspberry Pi で起動用 SD カードを作ると、OpenCV は入っていないものの、NumPy は入っています。
すると、OpenCV が動くか否かにかかわらず、NumPy のバージョンだけが上がっていく可能性がある（NumPy のバージョンが勝手に上がっていって、OpenCV が動かなくなる可能性がある）、ということになります。
依存関係に矛盾があり、opencv-python の設定時にエラーが起きやすい一因となっているように思われます。オープンソースの宿命か。。

参考：インストールが可能なバージョンの例

参考として、本記事の作成時点（2024年4月）で、Raspberry Pi (bullseye) にインストール可能な opencv-python のバージョン、および、インストール可能な NumPy のバージョンを抜粋しておきます。下記のカッコ (…) 内を参照してください。
インストールが可能なバージョンは、OS 環境によって、また、時期によっても変わります。正確には／詳細は実機で確認してください。

例：　pip install opencv-python==-1
ERROR: Could not find a version that satisfies the requirement opencv-python==-1 (from versions: 3.4.0.14, 3.4.10.37, 3.4.11.41, 3.4.11.43, 3.4.11.45, 3.4.13.47, 3.4.15.55, 3.4.16.57, 3.4.16.59, 3.4.17.61, 3.4.17.63, 3.4.18.65, 4.3.0.38, 4.4.0.40, 4.4.0.42, 4.4.0.44, 4.4.0.46, 4.5.1.48, 4.5.3.56, 4.5.4.58, 4.5.4.60, 4.5.5.62, 4.5.5.64, 4.6.0.66, 4.7.0.68, 4.7.0.72, 4.8.0.74, 4.8.0.76, 4.8.1.78, 4.9.0.80)

例：　pip install numpy==-1
ERROR: Could not find a version that satisfies the requirement numpy==-1 (from versions: 1.3.0, 1.4.1, 1.5.0, 1.5.1, 1.6.0, 1.6.1, 1.6.2, 1.7.0, 1.7.1, 1.7.2, 1.8.0, 1.8.1, 1.8.2, 1.9.0, 1.9.1, 1.9.2, 1.9.3, 1.10.0.post2, 1.10.1, 1.10.2, 1.10.4, 1.11.0, 1.11.1, 1.11.2, 1.11.3, 1.12.0, 1.12.1, 1.13.0, 1.13.1, 1.13.3, 1.14.0, 1.14.1, 1.14.2, 1.14.3, 1.14.4, 1.14.5, 1.14.6, 1.15.0, 1.15.1, 1.15.2, 1.15.3, 1.15.4, 1.16.0, 1.16.1, 1.16.2, 1.16.3, 1.16.4, 1.16.5, 1.16.6, 1.17.0, 1.17.1, 1.17.2, 1.17.3, 1.17.4, 1.17.5, 1.18.0, 1.18.1, 1.18.2, 1.18.3, 1.18.4, 1.18.5, 1.19.0, 1.19.1, 1.19.2, 1.19.3, 1.19.4, 1.19.5, 1.20.0, 1.20.1, 1.20.2, 1.20.3, 1.21.0, 1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.22.0, 1.22.1, 1.22.2, 1.22.3, 1.22.4, 1.23.0rc1, 1.23.0rc2, 1.23.0rc3, 1.23.0, 1.23.1, 1.23.2, 1.23.3, 1.23.4, 1.23.5, 1.24.0rc1, 1.24.0rc2, 1.24.0, 1.24.1, 1.24.2, 1.24.3, 1.24.4, 1.25.0rc1, 1.25.0, 1.25.1, 1.25.2, 1.26.0b1, 1.26.0rc1, 1.26.0, 1.26.1, 1.26.2, 1.26.3, 1.26.4, 2.0.0b1, 2.0.0rc1)

参考：典型的なエラーでの対処例

参考までに、過去に経験した典型的なエラーと対処方法についても挙げておきます。

例１：　”Building wheel for opencv-python (PEP 517)” と表示されて止まったままとなる。
→　opencv-python のバージョンを新旧変えて、インストールする。（上記のステップ２を実行する。）
例２：　”ImportError: numpy.core.multiarray failed to import
ModuleNotFoundError: No module named ‘cv2’ ” と表示される。
→　OpenCV (cv2) が正常にインストールされていない。
→　opencv-python のバージョンを新旧変えて、インストールする。（上記のステップ２を実行する。）
例３：　”RuntimeError: module compiled against API version 0xf but this version of numpy is 0xd” と表示される。
→　NumPy をアップグレードする。または、NumPy のバージョンを指定して（新旧変えて）インストールする。（上記のステップ３を実行する。）

まとめ

Raspberry Pi で OpenCV (opencv-python) のインストールがうまくいかないときの対処方法についてまとめました。

ネット検索をしても、全体の流れや考え方が書かれたものが見つかりませんでした。そこで、全体の流れと、エラーをどうやってなくしていくのかといった考え方の部分を明文化し、公開しておくことにします。
各プログラムのアップデートが頻繁で、環境を再設定したりすると、半年くらい前には動いていたはずのプログラムが動かなくなることもよくあります。オープンソースの世界はこういうものかなと。。

OpenCV がうまく動いたら、OpenCV を使ったサンプルスクリプトなども公開しています。関心があるようでしたら、関連リンクなども参照してみてください。

外部リンク
・　opencv-python · PyPI
・　Installing Packages – Python Packaging User Guide
・　NumPy 2.1.0 Release Notes
・　NumPy 2.0.0 Release Notes
・　NumPy 2.0 development status & announcements · Issue #24300 · numpy/numpy · GitHub
※　NumPy については、2024年に2006年以来となる NumPy 2.0.0 のメジャーリリースがあったとあります。内部の処理が大きく変わったと思われます。