Pythonで動く静的サイトジェネレータをpipでインストールしようと思ったら、エラーが出て、半日以上を費やす大格闘になったので、記事として残しておく。
もっとも当記事の執筆を含めると、丸1日以上を要しているが…。
対象とする読者
- Linuxについて、ある程度知っている方。
- Pythonについて、ある程度知っている方。
- （私のように）pipが出力する「error: externally-managed-environment」の内容が理解できない方。
【目次】
【広告欄】
本題
pip使用時のエラーメッセージ全文
$ pip3 install mkdocs
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.
初めてこのエラーに遭遇した際、Google翻訳にかけても、なんか良く分からん翻訳結果が出て理解不能だった。
このため、先人たちがネット上に残した記事を頼りに、何とか目的を達成できたのだが、あとからこの本文を読み返して、ようやく意味が理解できた。
以下の記事著者様について、この場を借りてお礼申し上げます。（ここだけ敬語）
Debian 系OSで pip を使う（Qiita／@nanbuwks 様）
venv: Python 仮想環境管理（Qiita／@fiftystorm36 様）
以下、段落ごとに、私独自の解釈で読み解いていく。
1段落目
【原文】 This environment is externally managed. 【Google翻訳結果】 この環境は外部で管理されています。
そのまま読むと「外部管理している事は分かった。だから何？」ということになると思う。AIでももう少し具体的に…いややめよう。人のこと言えないから。
実際に意味することは、pipと呼ばれるPythonのパッケージ管理システムでパッケージをインストールしようとしているが、Debianパッケージの管理対象外であるため、そのままではインストールできないと言っている。
この一文で真の意味まで読み取れる方が居たら「クイズ王か！」とツッコミを入れてあげたい。
現実世界で例えると、マクドの商品をミスドで注文されても困る、ということ。他社商品の管理なんて知らんがな、といった感じであろうか。
なお、「パッケージ」などの表現が合っているか、いまいち自信はない。
ひとつ確実なことは、このままでは希望するPythonパッケージがインストールできないということである。
この調子で、以降の段落も読み進めてみる。
2段落目
【原文】 To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install. 【Google翻訳結果】 Python パッケージをシステム全体にインストールするには、apt install python3-xyz を試してください。xyz はインストールするパッケージ名です。
「xyz はインストールするパッケージ名」という一文について、まぁシティーハンターへの仕事依頼や、カクテル名ではないとは思っている。一応。
私は当初、バージョン・リビジョンまで指定してPythonをインストールしろと読み取ったのだが、どうやら「python3-{pipモジュール名}」という、Debianパッケージをインストールしろと言っている模様。
実際、aptでパッケージを検索すると、膨大な量のPythonパッケージが表示される。
$ apt search python3- | grep -E '^python3-' | wc -l WARNING: apt does not have a stable CLI interface. Use with caution in scripts. 4298
上記コマンドを要約すると「python3-」と名前の付くパッケージを検索し、grepの正規表現で行頭が「python3-」から始まる行だけを抽出、最後に「wc -l」で改行数をカウントしている。
なお、改行数が4298であり、厳密にはパッケージ数でない。念のため。
ちなみに私が利用したいMkDocsは「python3-」に存在しなかった。
（実はMkDocsもDebianのパッケージとして存在する事に後から知ることになるが、話が長くなるので、今回は割愛。）
3段落目
【原文】 If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. 【Google翻訳結果】 Debian パッケージ以外の Python パッケージをインストールする場合は、python3 -m venv path/to/venv を使用して仮想環境を作成してください。
DebianパッケージにないPythonパッケージをインストールする場合は、venvという仮想環境作成ツールを使用して、Pythonパッケージ実行のための仮想環境を作成しろと言っている。
つまり、実環境に直接インストールするのではなく、Dockerコンテナのように仮想的に分離された環境内でPythonパッケージを実行しろと言っている。
それはともかく、本文とコマンドは分けて書いて欲しい。分かり辛いというか、上述したQiita記事を見るまで気付かなかった。
$ python3 -m venv path/to/venv
上記コマンドを要約すると、pythonの実行オプション-mでモジュール名のvenvを指定して、指定した相対パスにvenv仮想環境をディレクトリとして作成する。
4段落目
【原文】 Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed. 【Google翻訳結果】 次に、path/to/venv/bin/python と path/to/venv/bin/pip を使用してください。python3-full がインストールされていることを確認してください。
生成した（Python実行用）仮想環境と言うか、venvで作ったディレクトリ内にある、pythonとpipを使用（実行）しろと言っている。
続けて「python3-fullがインストールされていること」と書かれているが、実はvenvモジュールを実行するためには「python3-full」をインストールしなくてはならない模様。（※未検証）
説明の順番が逆。3段落目に書いておくれよ。
なお私は、当初この文を読まずに手当たり次第に進めて、aptで「python3-venv」をインストールしているので、「python3-full」については未検証。
【2025-08-24 追記】
「python3-venv」は「python3-full」の追加パッケージのひとつとして一緒にインストールされるので、目的によっては、私が試したように「python3-venv」のインストールだけでも可。
追記ここまで。
5段落目
【原文】 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. 【Google翻訳結果】 Debian パッケージ以外の Python アプリケーションをインストールする場合は、仮想環境を自動的に管理する pipx install xyz を使用するのが最も簡単です。pipx がインストールされていることを確認してください。
ここまで書いて何だが、実は、Pythonアプリケーションと言っているのは、日本で言うPythonモジュール（部品）のことらしく、そもそもPython界隈でも言葉が統一されていないのが、混乱の元凶にある模様。
そして、Pythonモジュールを利用するためには、pipxパッケージのインストールが最も簡単である、と言っている。
最初に言えよ、とツッコミたくなる。
なお、pipxについては未検証だが、既にWSL内の環境がぐちゃぐちゃになっているので、Debianを再インストールしてから試してみたいと思う。
WSLだけで完結する話なのでOS再インストールも楽。
あとがきというか余談
本当は当記事に書いている以上に、もっと色々試しては戻しを繰り返している。
だが私が試したものを全部書くと、とてつもない文字数になるため、pip実行時のエラーメッセージを読み解くという部分にだけに集中して、1本の記事とした。
そもそも、今回記事を書いていて更に検証事項が増えてしまったが、本題であるMkDocsでのwebページ作りに全然進めていない。先は長そうである。
