SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

サーバーのPython環境はvenv、pipx、uvのどれ?

Ubuntu 24.04でpip installがexternally-managed-environmentになる理由を確認し、用途別にvenv、pipx、uvを選ぶ方法とsystemdの指定方法を解説します。

新しい Ubuntu サーバーで pip install が失敗する理由

Python venv、pipx、uv のどれをサーバーで使うかは、何をインストールするかで決まります。アプリケーションの依存関係は、アプリケーション専用ディレクトリ内の仮想環境に入れます。名前を入力して実行するコマンドラインツールは pipx に入れます。uv はこの両方に対応し、lockfile も追加します。同じ環境を 2 台目のマシンで構築する必要が生じると、lockfile が重要になります。これらのツールは、システムの Python にはインストールしません。現在の Ubuntu サーバーが、それを明確に拒否するためです。

Ubuntu 24.04 で sudo pip install requests を実行すると、pip は 1 つもファイルをダウンロードせずに停止します。

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.

    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.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.

これは PEP 668(Python enhancement proposal 668、「externally managed environments」)の動作です。Debian と Ubuntu は、インタープリターの隣に /usr/lib/python3.12/EXTERNALLY-MANAGED のマーカーファイルを配置します。pip は、そのマーカーを持つインタープリターへの書き込みを拒否します。

このルールが存在するのは、sys.path の順序が原因です。apt はライブラリを /usr/lib/python3/dist-packages にインストールします。root としてシステムのインタープリターに対して実行した pip は /usr/local/lib/python3.12/dist-packages に書き込みます。Debian のパッケージングでは、このディレクトリが検索パスの前方に配置されます。python3 -c 'import sys; print(sys.path)' で自分でも表示し、その順序を確認できます。そのため、pip が書き込んだコピーが apt のインストールしたコピーを上書きします。/usr/bin/python3 で実行される、このサーバー上のすべてのプログラムが影響を受けます。ディストリビューション独自のツールも例外ではありません。cloud-init は、このインタープリターから requests、jinja2、PyYAML をインポートします。これらのいずれかを pip でアップグレードして互換性のないリリースになると、次回のブート時に、依存関係に含まれるとは知らなかったパッケージ名を示す traceback とともに、変更していない機能が失敗することがあります。apt は自分が管理するバージョンをインストール済みとして記録したままなので、警告は表示されません。修復するには、sudo pip uninstall --break-system-packages requests で pip のコピーを削除します。sudo apt reinstall python3-requests だけでは、すでに隠れている apt のコピーを書き換えるだけだからです。

ここから導かれるルールは簡単です。システムの Python はディストリビューションが管理します。システムの Python にはインストールしないでください。pip でそのライブラリをアップグレードしないでください。メッセージを消すために EXTERNALLY-MANAGED ファイルを削除しないでください。/usr/bin/python3 に任せるのは、仮想環境の構築だけです。

venv、pipx、uv: 選択の基準

何をインストールするかを基準に選びます。最近読んだツールで選んではいけません。

  • サービスとしてデプロイして実行するアプリケーション(Django または Flask プロジェクトなど): アプリケーションのディレクトリ内に 1 つの仮想環境(venv)を作成します。
  • PATH 上で使用するコマンドラインツール(ansible や httpie など): pipx を使います。各ツール専用の環境と、PATH 上のリンクが作成されます。
  • lockfile、高速なインストール、またはディストリビューションが提供していない Python バージョンを必要とするプロジェクト: uv を使います。通常の venv と uv.lock ファイルが作成されます。
  • コードではなく、ディストリビューションのツールが必要とするライブラリ: sudo apt install python3-<name> を使います。システムインタープリターに何かを追加するためにサポートされている唯一の方法です。

pipx と uv tool install は同じ役割を担うため、すでに uv がある環境に pipx も用意する必要はありません。選択した Web フレームワークによる違いはありません。VPS 上の Django と Flask は requirements.txt に配置されるものが異なるだけで、その周囲の環境の構築方法は変わりません。以下では Ubuntu 24.04 とその Python 3.12 を使用します。環境が異なる場合は、パス内のバージョンを調整してください。

アプリケーションごとの venv を作成する

Ubuntu では venv モジュールが基本の Python パッケージから分離されています。そのため、最小構成のイメージでは最初の試行が失敗し、不足しているものを示すメッセージが表示されます。

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.12-venv

venv をインストールし、コードの所有者となるユーザーで環境を作成します。

sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txt

ここで、存在しないものにも注目してください。source も activate もありません。/srv/myapp/.venv/bin/pip がその環境にインストールされるのは、バイナリの場所によるものです。シェルで何かを export したためではありません。先に進む前に確認します。

/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'

/srv/myapp/.venv と表示されます。/usr と表示された場合は、システムのインタープリターを実行しており、パッケージが意図しない場所にインストールされています。

venv のその後の扱いは、2 つの性質によって決まります。venv は移動できません。bin/ 内のすべてのエントリーポイントスクリプトに、絶対パスの shebang 行が含まれているためです。head -1 /srv/myapp/.venv/bin/pip は #!/srv/myapp/.venv/bin/python を読み込みます。親ディレクトリの名前を変更すると、これらのスクリプトは bad interpreter: No such file or directory で失敗します。venv には、作成時に使用したインタープリターも固定されています。これは /srv/myapp/.venv/pyvenv.cfg の home 行に記録され、bin/python3 は /usr/bin/python3 へのシンボリックリンクです。リリースをアップグレードして、そのパスが新しい Python を指すようになると、新しいインタープリターは venv に存在しない lib/python3.13 ディレクトリでパッケージを探します。そのため、サービスは起動時に ModuleNotFoundError で停止します。どちらの場合も対処方法は同じです。venv を削除し、requirements.txt から新しく作成します。再作成には数秒しかかかりません。venv をマシン間でコピーしないでください。

venv の配置場所と所有者

コードを /srv/myapp/.venv に配置し、その隣に置きます。アプリケーションごとに venv を 1 つ用意してください。これでデプロイ対象が 1 つのディレクトリにまとまり、systemd unit には変わらないパスを指定でき、共有依存関係のアップグレードによって 2 つのアプリケーションが互いに壊れることもありません。Web サーバーがファイルを直接公開する場所には venv を配置しないでください。venv には依存関係が含まれ、多くの場合は設定も含まれるためです。

所有者の設定にも少し時間をかけてください。deploy ユーザーにコードと環境の所有権を持たせ、サービスアカウントには読み取りと実行の権限だけを付与します。

sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myapp

これでサービスは依存関係をインポートできますが、依存関係を書き換えることはできません。つまり、Web アプリケーションのコード実行バグがディスク上のライブラリを密かに置き換え、再起動後も残る事態を防げます。マシンの他の部分にも同じ考え方を適用する方法については、最小権限のユーザーでサービスを実行するで説明します。

コマンドラインツール向けのpipx

pipxはライブラリではなくアプリケーションをインストールします。各ツールには~/.local/share/pipx/venvs/<name>配下に専用の環境が作成され、そのツールの実行ファイルは~/.local/binにリンクされます。そのため、同じライブラリの異なるバージョンを必要とする2つのツールが競合することはありません。

sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpie

pipx ensurepathは、シェルの起動ファイルを編集して~/.local/binをPATHに追加します。現在使用しているシェルの環境は変更できません。そのため、インストール直後にhttp: command not foundと表示される場合は、通常、まだログアウトして再ログインしていません。Ubuntuのデフォルトの~/.profileは、ログイン時点ですでにそのディレクトリが存在する場合にだけ~/.local/binを追加します。そのため、新しいアカウントで初回だけ問題になります。

pipxにライブラリを指定すると、次の文字列で始まるメッセージを表示して拒否します。

No apps associated with package requests.

これは、指定された対象にpipxが適していないという意味です。ライブラリはアプリケーションのvenvにインストールしてください。

サーバーでは、インストール先が重要です。通常のpipx installでは、すべてが1人のユーザーのホームディレクトリ配下に置かれます。myappとして実行されるsystemd unitからは参照できず、rootのcronジョブからも参照できません。sudoでも見つかりません。/etc/sudoers内のsecure_pathがPATHを固定されたリストで置き換えるためです。マシン全体で使用するツールは、グローバルにインストールしてください。

sudo pipx install --global ansible
sudo pipx ensurepath --global

--globalフラグを指定すると、環境は/opt/pipxに作成され、実行ファイルは/usr/local/binにリンクされます。/usr/local/binはデフォルトのPATHに含まれ、secure_pathの配下にもあります。まずpipx --versionでバージョンを確認してください。Ubuntu 24.04のpipxは1.4.3をパッケージ化しており、これは--globalより古いため、古いpipxではunrecognized arguments: --globalと表示されます。そのバージョンでは、ドキュメントに記載された2つのディレクトリを自分で設定します。

sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansible

command -v ansibleの出力は/usr/local/bin/ansibleになるはずです。/home配下のパスが表示された場合、そのツールは1人のユーザーのアカウントにインストールされています。その場合、サービスからは見つかりません。

lockfile が必要な場合の uv

uv は Astral が提供する単一バイナリです。pip、venv、pip-tools が担う機能をまとめて提供し、インタープリターのダウンロードにも対応します。小規模な VPS でも速度差が分かるほど高速で、実際の lockfile を生成します。

公式インストーラーは uv と uvx を ~/.local/bin に配置します。

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

サーバー上でスクリプトを shell にパイプする場合は、慎重に扱う必要があります。URL でバージョンを固定し、実行前にファイルを確認してください。

curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.sh

pipx がすでに存在する場合は、pipx install uv も使用できます。uv は独立した単一バイナリで、独自の Python 依存関係を持ちません。そのため、/usr/local/bin にコピーすれば、サーバー上のすべてのユーザーで共有できます。

pyproject.toml を持つプロジェクトでは、ワークフローは 4 つのコマンドで完了し、サーバー上で実行するのは最後のコマンドだけです。

uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-dev

uv lock は uv.lock を生成します。これは解決済みの正確なバージョンを保持する、クロスプラットフォームの lockfile です。これをコードと同じ場所でコミットします。uv sync は、プロジェクトのルートに .venv を作成し、lockfile に合わせます。サーバーでは --frozen が重要なフラグです。ドキュメントでは、lockfile が最新かどうかを確認する代わりに、lockfile のバージョンを正しい値として使用するフラグと定義されています。これはデプロイに適した動作です。--no-dev を指定すると、開発用の依存関係グループが除外されます。

既存の requirements.txt プロジェクトは変換する必要がありません。uv は pip の形式に対応しているためです。

uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txt

作成されるのは通常の仮想環境ですが、1 つ違いがあります。uv は仮想環境に pip をインストールしません。そのため、uv venv --seed を指定して環境を作成しない限り、.venv/bin/pip と .venv/bin/python -m pip は機能しません。代わりに uv pip を指定してインストールしてください。このガイドの後続手順では仮想環境内で pip を実行しないため、以降の動作は変わりません。

サーバーで使用する前に、uv のデフォルト設定を 1 つ確認しておくとよいでしょう。python-preference 設定のデフォルト値は managed です。ドキュメントでは、システムにすでに存在するインタープリターよりも「uv がダウンロードしてインストールするもの」を選択する設定と説明されています。そのため、3.12 しか搭載していないサーバーで uv venv --python 3.13 を実行すると、失敗せずに 3.13 を ~/.local/share/uv/python に取得します。これはノート PC では便利ですが、サーバーでは予想外の結果になります。サービスがホームディレクトリにあるインタープリターに依存し、そのインタープリターを apt upgrade が更新できないためです。ディストリビューションのインタープリターを使用する場合は、uv.toml で python-preference を only-system に設定してください。プロジェクトのルート以外に環境を配置する場合は、UV_PROJECT_ENVIRONMENT でプロジェクトの仮想環境に使用するディレクトリを指定します。

venv の interpreter を systemd に指定し、activate は指定しない

Python のデプロイで最も多く問題が起きる箇所です。原因は activate の動作を誤解していることです。

bin/activate は shell script です。venv の bin directory を PATH の先頭に追加し、VIRTUAL_ENV を設定し、deactivate が元の値を復元できるように以前の値を保存し、prompt を変更します。interpreter 自体が読み取る内容は含まれていません。Activation は、prompt で人が python を入力するための利便機能です。

実際に環境を選択するのは、実行する interpreter file です。/srv/myapp/.venv/bin/python の起動時に、Python の site module は executable を格納している directory と、その 1 つ上の directory に pyvenv.cfg file があるかを探します。/srv/myapp/.venv/pyvenv.cfg が見つかると sys.prefix が venv に設定され、その venv の site-packages が sys.path に追加されます。仕組みはこれだけです。環境変数も shell も必要ありません。

そのため、この unit は起動しません。

[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:app
myapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXEC

ExecStart は shell command line ではありません。systemd は program を直接実行するため、source builtin は存在せず、&& は文字どおりの argument として渡され、systemd 自身が定義している一部の展開を除いて、shell の展開は行われません。

一方、この unit は起動した後に終了します。

[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.py
ModuleNotFoundError: No module named 'flask'

/usr/bin/python3 は system interpreter であり、その sys.path に対象の venv が含まれたことはありません。SSH session で同じ command が動くのは、その session で venv を activate していたためです。その結果、shell が python3 を PATH 経由で .venv/bin/python3 に解決していました。

command を /bin/bash -c 'source ... && gunicorn ...' でラップすれば動作します。ただし、1 つの absolute path で解決できる問題のために、systemd と process の間に shell を挟むことになります。

[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pager

systemctl status myapp では、Main PID に gunicorn process が含まれる状態で active (running) が表示されるはずです。それ以外の場合は journal を確認してください。

Environment=PATH= line は、すでに full path を持つ ExecStart のためにあるのではありません。application が起動する process のために指定します。service は systemd から短い default PATH を継承します。そのため、Python code が subprocess.run(["ffmpeg", ...]) を呼び出す場合や、venv の console script を management command から shell 経由で実行する場合に、必要な command が見つからないことがあります。venv の bin directory を先頭に置くことが、service が実際に利用する activate の唯一の部分です。unit が実際に受け取った内容は systemctl show -p Environment myapp で確認してください。

同じルールは scheduled work にも適用されます。Ubuntu では、cron は shell または daemon の PATH を job に渡しません。crontab 自体で PATH を設定しない限り、すべての job には compile 時の default /usr/bin:/bin が設定され、/etc/environment で上書きされることもありません。そこに venv は含まれないため、python3 /srv/myapp/cleanup.py と記述した crontab line は system interpreter を実行し、午前 3 時に ModuleNotFoundError で失敗します。cron は error を crontab の owner、または MAILTO address を設定している場合はその宛先に mail で送信します。ただし、ほとんどの server では、誰も読まない local mailbox が宛先になります。mail program がインストールされていない場合、cron は output を破棄し、system log に No MTA installed, discarding output だけを書き込みます。ここにも venv の absolute path を記述してください。output を journal に記録し、直近の実行結果を残すには、systemd service と timer の組み合わせで同じ ExecStart line を使用できます。

Docker でこの判断は不要になりますか?

コンテナには独自のファイルシステムがあるため、問題はなくなるのではなく、形が変わります。python:3.12-slim などの公式イメージでは、Python は /usr/local に組み込まれており、EXTERNALLY-MANAGED マーカーを持たないため、root として pip install する方法が想定されています。venv を追加しても、ほとんどメリットはありません。代わりに FROM ubuntu:24.04 をビルドすると、イメージ内でも externally-managed-environment に直面します。これはホスト上と同じ理由です。ディストリビューションのインタープリターが、ディストリビューションのマーカーファイルを持っているためです。

それでも、多くのイメージでは venv を使用します。マルチステージビルドを簡単にできるためです。builder ステージでは /opt/venv にインストールし、runtime ステージではそのディレクトリだけをコピーして、コンパイラーを残しません。activate に関する問題も、そのまま引き継がれます。RUN source /opt/venv/bin/activate の行が影響するのは、そのビルドレイヤーの shell だけです。そのため、実行時にはコンテナが system interpreter で起動し、ModuleNotFoundError が発生します。ENV PATH="/opt/venv/bin:$PATH" を設定するか、CMD に絶対パス /opt/venv/bin/gunicorn を指定してください。これは、別のファイルで発生する systemd の問題と同じです。

したがって、コンテナではイメージがインタープリターとその配下のすべてを固定するため、インタープリターに関する問題は置き換わります。しかし、バージョン固定に関する問題は置き換わりません。固定されていない requirements.txt からビルドしたイメージでは、来月になると異なるバージョンが解決される可能性があります。つまり、イメージタグは再現可能でも、それを生成したビルドは再現可能ではありません。uv.lock のような lockfile、または完全に固定した requirements ファイルによって、コンテナを使用するかどうかにかかわらず、この差を埋められます。また、1 台の VPS 上で systemd により 1 つのアプリケーションを実行する場合、コンテナはこの判断を主に Dockerfile へ移すだけです。systemd はすでに、失敗したプロセスを再起動し、その出力を journal に記録するためです。VPS で Docker を実行する は、ビルド済みイメージ自体をデプロイ対象にしたい場合に有効です。

FAQ

--break-system-packages を付けて pip install を実行してもよいですか?

稼働を維持する必要があるサーバーでは、避けてください。このフラグは名前のとおり保護機能を解除し、pip は /usr/local/lib/python3.12/dist-packages に書き込みます。このパスは sys.path の apt ディレクトリより先に検索されます。そのため、/usr/bin/python3 で実行されるすべてのシステムスクリプトで、インストールしたバージョンがディストリビューションのバージョンを隠します。一方、apt は自身のバージョンがインストールされていると認識したままなので、何かが壊れるまで競合は検出されません。毎回ゼロから再構築するコンテナイメージ内なら、影響はそのイメージ内にとどまるため、使用しても問題ありません。管理対象のマシンでは venv を作成してください。1 コマンドで実行できます。

サーバー上の仮想環境はどこに配置すべきですか?

アプリケーション専用ディレクトリ内に /srv/myapp/.venv として配置し、deploy ユーザーが所有するようにします。サービスアカウントには読み取りと実行のみを許可します。アプリケーションごとに 1 つの venv を使用してください。共有すると、最初のアプリケーションのアップグレードで 2 番目のアプリケーションが壊れる可能性があります。作成後の venv は移動またはコピーしないでください。bin/ ディレクトリ内のすべてのエントリポイントスクリプトには、その絶対パスが shebang 行に書き込まれています。そのため、移動した venv は bad interpreter: No such file or directory で失敗します。削除して、requirements.txt から再構築してください。

systemd サービスが ModuleNotFoundError で失敗するのはなぜですか?

unit が venv のインタープリターではないインタープリターを実行しているためです。systemctl cat myapp を実行し、ExecStart を確認してください。絶対パスで /srv/myapp/.venv/bin/python、または同じ bin/ ディレクトリにあるコンソールスクリプトを指定している必要があります。activate を ExecStart で直接 source しても動作しません。ExecStart はシェルではないため、systemd は Failed to locate executable source と status=203/EXEC を報告します。Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin を追加し、コードが起動するサブプロセスでも venv のツールを見つけられるようにしてください。

venv と pip の代わりに uv を使用すべきですか?

lockfile が必要な場合、インストール時間が長く負担になっている場合、またはディストリビューションが提供していない Python バージョンが必要な場合は、uv を使用してください。uv は通常の venv を作成するため、systemd の unit とファイル構成は変わりません。uv sync --frozen は lockfile に記録された内容を正確にインストールします。git から固定した requirements.txt を使って単一のアプリケーションをデプロイし、インストールが数秒で完了するなら、python3 -m venv で十分です。サーバー上で更新を続けるバイナリが 1 つ減ります。

この記事は役に立ちましたか?