Q. CircleCIでPEP 668エラーが発生するようになった
いくつかの CircleCI を利用しているプロジェクトで、ある時期を境に PEP 668 エラーが発生するようになった。 これは CircleCI が提供する Docker イメージの Ubuntu が非自明的に上がることにより、意図せず PEP 668 に従った Ubuntu 24.04 になってしまったことによる。
エラーの発生
cimg/node:22.17.0またはcimg/go:1.24.5に更新された job で、pip install実行時に次のエラーが出力されていた。
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`....hint: See PEP 668 for the detailed specification.なぜこのエラーが発生したのか
今回のケースではcimg/nodeのマイナーバージョン更新で、基盤となる Ubuntu のバージョンが大幅に変わっていた。
cimg/node:22.16: Ubuntu 22.04.5 LTScimg/node:22.17: Ubuntu 24.04.2 LTS
Ubuntu 24.04 で PEP 668 が採用されたため、システムグローバルな環境へのpip installがブロックされるようになった。
またcimg/goの場合は、パッチバージョンの更新により Ubuntu のバージョンが変わっていた。
cimg/go:1.24.4: Ubuntu 22.04.5 LTScimg/go:1.24.5: Ubuntu 24.04.2 LTS
各イメージで利用されている OS は次のページで確認できる。
Ubuntu の更新は四半期毎に行われる
cimg/nodeやcimg/goが利用する Linux のバージョンは、親イメージであるcimg/baseから継承されている。
ベースイメージであるcimg/baseと、ベースイメージを継承した子イメージについて CircleCI は次のようなポリシーを採用している。
We build a new base image each month. However, we only update the base image used in child convenience images once per quarter. These updates are not retroactively applied to existing images, but will apply to new releases of the image after the change has been made.
出展：CircleCI Convenience Images Support Policy
ベースイメージ自体は月次で更新されるが、子イメージでは四半期ごとに利用されるベースイメージが更新される。つまり、パッチやマイナーに関わらず子イメージの OS バージョンが Ubuntu 22.04.5 から Ubuntu 24.04.2 のようなジャンプをする可能性があり、これをバージョンが推測することが困難である。
このポリシーによる問題は、今までにも事例が報告されている。
PEP 668 について
PEP 668 は、OS のパッケージマネージャー（aptやyum）とpipの競合を避けるための仕様。Ubuntu 24.04 から採用されている。
要するに、システムグローバルなpip installがデフォルトでブロックされ、仮想環境（venv）での管理が必須になった。これによりerror: externally-managed-environmentエラーが発生する。
出展：PEP 668 – Marking Python base environments as “externally managed”
解決方法
いくつかの対処法があるが、対象によって CircleCI Orb や OS のパッケージマネージャーを利用することが好ましいと思われる。
1. CircleCI Orb の使用
例えば AWS CLI のように Orb が提供されているものであれば、Orb を利用することで解決する可能性が高い。
orbs:
jobs: build: docker: - image: cimg/node:22.17.0 steps: - checkout - aws-cli/setup参考：https://circleci.com/developer/ja/orbs/orb/circleci/aws-cli#commands-setup
2. パッケージマネージャーの使用
システムのパッケージマネージャーを使えば、PEP 668 に従ったインストールが可能。
steps: - run: name: Install AWS CLI command: | apt install -y awscli3. 仮想環境の使用（非推奨）
PEP 668 に従う形で、Python 仮想環境を作成してパッケージをインストールすることでも回避できるが、Python のプロダクトでも無ければ無駄が大きくなる可能性が高い。
steps: - run: name: Install AWS CLI in virtual environment command: | python3 -m venv venv source venv/bin/activate pip install awscli4. 強制的な回避（非推奨）
--break-system-packagesフラグで強制的に回避できるが、システムの安定性を損なう可能性があるため推奨できない。
steps: - run: name: Force install AWS CLI (not recommended) command: pip3 install --break-system-packages awscliGitHub Actions との比較
ちなみに、GitHub Actions では同様の問題が発生した後に対応が取り込まれ、pip がデフォルト環境にパッケージをインストールできるようになっている。
出展：