Ubunt24.04でpip install時に"error: externally-managed-environment"エラーが出た時の対処法

概要

Ubuntu24.04でPythonのパッケージをpipでインストールしようとすると、以下のようなエラーメッセージが表示されてインストールが失敗することがあります。

$ pip install numpy
error: externally-managed-environment

× 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.
   
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
   
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
   
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

このエラーの原因と解決策について紹介します。

エラーの原因

　上記のエラーは、一部のOS（Ubuntu24.04やDebian12）において、システムPython（システム上にインストールされている、いわば大元のPython）に直接pipでパッケージをインストールすることを制限する機能により発生しています。
　後述の解決策1でも記載しているように、システムPythonに直接パッケージをインストールすることは、様々な問題を引き起こす原因となるため、基本的に非推奨となります。本エラーはこのようなシステムPython上へのパッケージインストールを防ぐため、Debian系OSにおいて実装されているようです。

解決策

以下の方法を用いることで、上記のエラーが発生する環境であってもpipでPythonのパッケージがインストールできるようになります。

• 解決策1: 仮想環境を使う（原則この方法を推奨）
• 解決策2: aptでPythonパッケージをインストールする
• 解決策3: --break-system-packagesオプションを付ける

解決策1: 仮想環境を使う（原則この方法を推奨）

　エラーメッセージにもcreate a virtual environmentと書かれているように、本来Ubuntu上でPythonのパッケージを使用する際は仮想環境を構築することが推奨されています。これにより環境の再現を容易化したり、無秩序にパッケージがインストールされて不具合の原因となることを防ぐことができます。
　仮想環境の作成方法とパッケージのインストール方法については、以下の記事を参照ください（迷ったらデフォルトで使用できるvenvを使うと良いと思います）。

　上記の記事はやや古いので、uv等の新しいツールについては触れていません（uvについては私も良く分かっていないので、適宜調べていただければと思います）。
　また、Python以外の環境も仮想化する手段として、Dockerを使用することも有効です。

解決策2: aptでPythonパッケージをインストールする

　ここからがこの記事の本題ですが、使用したいプラットフォームによっては、どうしてもシステムPythonにパッケージをインストールせざるを得ない状況が発生します。

　例えば私のケースでは、ROS（Robot Operating System）のノード内でPythonのパッケージを使用する必要がありました。ROSは基本的にシステムPythonを参照して動作するため、ノードからNumpy等のパッケージを利用するためには、システムPython上にインストールする必要が生じます。

　このようなケースにおいて、NumpyやPandas等の有名なパッケージは、aptを用いることでエラーを発生させることなくインストールすることができます。

・Numpyのインストール例

sudo apt update
sudo apt install python3-numpy

解決策3: --break-system-packagesオプションを付ける

こちらは非推奨ですが、pip install時に--break-system-packagesオプションを付けることで、上記エラーを発生させることなく強制的にパッケージをインストールすることができます。

・Numpyのインストール例

pip install numpy

この方法は、バージョンを指定したい場合等に便利です。

・バージョンを指定したNumpyのインストール例

pip install numpy==1.24.3 --break-system-packages