頑張らないために頑張る

ゆるく頑張ります

externally-managed-environmentエラーへの対処法

Posted at — Oct 28, 2023

概要

pip installコマンドでライブラリをインストールしようとした時に、次のようなエラーが発生することがあります。

$ pip install -U pygame --user
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.
    
    For more information visit http://rptl.io/venv

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.

この externally-managed-environment エラーは、pipによるPython固有のパッケージ管理と、OS管理によるパッケージマネージャの競合を解消するために導入されたPEP668に基づくエラーです。

とりあえず、まずは表示されたエラーメッセージを見てみましょう。

エラー: 外部管理環境

× この環境は外部で管理されています
╰─> Pythonパッケージをシステム全体にインストールするには、apt install
    python3-xyz（xyzはインストールしようとしているパッケージです。）
    をインストールします。
    
    Debianパッケージ以外のPythonパッケージをインストールしたい場合、
    python3 -m venv path/to/venv を使って仮想環境を作ります。
    そしてpath/to/venv/bin/pythonとpath/to/venv/bin/pipを使います。そして
    python3-fullがインストールされていることを確認してください。
    
    詳しくはhttp://rptl.io/venv。

note: もしこれが間違いだと思うのであれば、PythonのインストールやOSの配布元に連絡してください。Python のインストールや OS が壊れる危険を冒してでも、 --break-system-packages を渡すことでこれを上書きすることができます。
hint: 詳細な仕様は PEP 668 を参照してください。

見てみると、「パッケージをインストールするならapt install使えよ、じゃなければ仮想環境を作れよ。詳しくはPEP668で検索！」という感じだそうです。

ちょっと待って、PEP668って何ぞ？

PEP668とは

PEP668とは、Pythonのパッケージ管理ツールと、OSのパッケージマネージャの競合を解決するためのPEPです。

PEP668が制定された目的

Pythonのパッケージをインストールするには、大きく分けて2つの方法があります。

ところが、apt install python-pygameとpip install pygameでは、「Pygameを導入するぜ」という行為そのものが同じであるものの、OS固有のパッケージ管理機能からするとpipでインストールされたパッケージは管理外です。そのため、不用意に使うとOSのPython環境に対して悪影響を与える可能性があります。

PEP668は、この問題を解決するための新しいルールです。

これで、Pythonのアプリケーションと基本ソフトのアプリケーションが競合しなくなり、安全にPythonを利用できるようになります。

PEP668がもたらすメリットとデメリット

メリット

デメリット

PEP668の影響範囲

対処法

このエラーを解決するには、いくつかの対処法があります。

  1. エラーを無視してとにかくインストールする
  2. 仮想環境を構築してその環境に対しインストールする

エラーを無視してとにかくインストールする

何らかの理由で「いろいろ余裕がない」とか、「どんなに壊れても構わない」という場合は、この方法がたぶん一番早いと思います。それは、--break-system-packagesオプションを付与することです。これで、従来どおりインストールできます。

pip install --break-system-packages pygame

ちなみに、アンインストール時も同様に--break-system-packagesオプションを付与することで、エラーに悩まされず従来どおりアンインストールできます。もちろん、自己責任ですが。

仮想環境を構築してその環境に対しインストールする

PEP668が制定された目的に沿うなら、こっちの方法が正攻法です。そもそも、現状では仮想環境を作成してその中でパッケージをインストールするのが一般的だと思います。

venvを使う

python -m venv venv # 仮想環境の作成
source venv/bin/activate # 仮想環境のアクティベート
pip install pygame # パッケージのインストール

このように、venvを使って仮想環境を設定することで、pip installエラーを回避できます。

PEP668が制定された背景や理由を鑑みると、可能な限り仮想環境を構築したうえでPythonを使用することをオススメします。

venv以外の仮想環境を使う

何らかの理由でvenvを利用せず、他の方法でPythonの仮想環境を構築する場合でもこのエラーが発動する可能性があります。この場合も、--break-system-packagesオプションを付与してインストールしてしまうのが最短です。

参考

  1. PEP668
  2. venv
  3. 俺流！PEP668とうまくやっていく方法
  4. Pythonライブラリ導入時のapt/pipの違いについて
  5. pip install -r requirements.txt is failing: “This environment is externally managed”
  6. How do I solve “error: externally-managed-environment” every time I use pip 3?
  7. How to Fix the pip “externally-managed-environment” Error on Linux
  8. 2021年のPython仮想環境〜いまやvenvを使わない理由はありません〜
  9. venvで手軽にPythonの仮想環境を構築しよう
comments powered by Disqus