uv を使用するとプロジェクトフォルダに仮想環境として .venv ディレクトリが作成されるのがデフォルトの動作となっているが、Docker コンテナ内で uv を使用している場合はすでにコンテナによって隔離された環境が作られているにも関わらず、さらに venv によって仮想環境を作られてしまうことになる。これは二重で環境を隔離することになっていてなんだか気持ち悪いし、PATH を通したりするのも面倒くさいのでできればやめたい。

Poetry のときは poetry config virtualenvs.create false によって仮想環境を作らない選択ができたが、uv の場合はバージョン 0.4.4 で追加された環境変数 UV_PROJECT_ENVIRONMENT を設定することで同じことが実現できるようだ。

以下の Dockerfile では、環境変数 UV_PROJECT_ENVIRONMENT にシステム Python がインストールされているパス /usr/local を指定することで仮想環境を作成せずにシステム Python 環境に直接パッケージをインストールするようにしている。

Dockerfile

FROM python:3.13

ENV UV_PROJECT_ENVIRONMENT /usr/local

RUN pip install uv

どうやらこの機能自体が Docker や CI といった既に隔離されている環境で使用することを想定して作られたらしい。

この PR にも書いてあるが、uv sync はプロジェクト依存関係に存在しないパッケージを削除する挙動をするので、適切に隔離できていない (≒ 他の Python プロジェクトから参照されるような) Python 環境でこの設定を使うと環境が壊れてしまうことになりかねないので注意されたい。