Raspberry Pi OSでのerror: externally-managed-environmentの対処方法

導入

Raspberry Piを触っていると、Pythonを扱う際にどこかしらでpip installをしてパッケージインストールをすると思いますが、error: externally-managed-environmentというエラーが発生することがあります。
その際にどうすれば良いのかを備忘録的に残しておこうと思います。

事例

私は、Raspberry PiにLEDパネルを接続して遊ぼうとしたので、以下のpipコマンドでモジュールをインストールしようとしていました。

pip install rpi_ws281x adafruit-circuitpython-neopixel

そうすると、以下のエラーが発生しました。

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
...

みたいなエラーが出ます。
最後の方まで読むと、PEP668に詳細があると言うことで、Abstractの3段落目に以下の記述を発見しました。

This PEP proposes a mechanism for a Python installation to communicate to tools like pip that its global package installation context is managed by some means external to Python, such as an OS package manager. It specifies that Python-specific package management tools should neither install nor remove packages into the interpreter’s global context, by default, and should instead guide the end user towards using a virtual environment.

簡潔に言うなら、「直接pipでパッケージインストールせずに、仮装環境でインストールしてね」というお話のようです。
Raspberry Pi OSもそうですが、同じDebian系のLinuxであるUbuntuの方でも発生しているようで、検索すると、同様のエラーが発生しているUbuntuの記事がヒットします。

解決方法

オプションに--break-system-packagesを用いる

https://packaging.python.org/ja/latest/specifications/externally-managed-environments/
Pythonパッケージガイドにも書いてありますが、仮想環境を使えない場合はこちらの選択肢になります。

おそらく、Raspberry Piだとこちらがベストプラクティスかなと思います。理由としては、大体1台のRaspberry Piで使うPythonプロジェクトは多岐にわたることは少ないと思うので。
pipコマンドを使用する際に、

pip install　[パッケージ名] --break-system-packages

のようにすればOKです。他の原因がなければ、インストールすることができます。

venvを使う

もう一つは、言われている通りに仮想環境にインストールしてあげるというものです。
仮想環境はいろいろありますが、Pythonでよく使うのはvenvなので、Pythonのプロジェクトのルートディレクトリに、

python3 -m venv [任意の名前(通常は.venv)]

とやって、

source [任意の名前(通常は.venv)]/bin/activate

みたいな感じで仮想環境をactivateした状態でpipをインストールすれば、上記のエラーは発生しないです。
もし仮想環境がわからなかったら、他の人が詳しく書いてくれているはずです。
あとは以下を参考までに。
https://docs.python.org/ja/3/library/venv.html

さいごに

pipが仮想環境なしでの使用を非推奨にしたことを知らず、驚きました。しかし、Pythonはパッケージが非常に豊富で、多様なプロジェクトで活用されるため、プロジェクトごとにパッケージを管理するのが一般的になっています。今回の改訂はその流れに沿った合理的なものなのでしょうね。