Python環境

各Pythonインストールには、Pythonが使用されるときにアクティブになる環境があります。パッケージを環境にインストールして、Pythonスクリプトからそのモジュールを利用できるようにすることができます。一般的に、Pythonインストールの環境を変更しないことが最善の方法とされています。これは特に、パッケージを自分で管理することが多いオペレーティングシステムに付属するPythonインストールにとって重要です。仮想環境は、Pythonインストールの環境からパッケージを分離する軽量な方法です。pipとは異なり、uvはデフォルトで仮想環境の使用を要求します。

仮想環境の作成

uvは仮想環境の作成をサポートしています。例えば、.venvに仮想環境を作成するには：

$ uv venv

特定の名前やパスを指定することもできます。例えば、my-nameに仮想環境を作成するには：

$ uv venv my-name

Pythonバージョンを指定することもできます。例えば、Python 3.11で仮想環境を作成するには：

$ uv venv --python 3.11

これは、指定されたPythonバージョンがシステム上で利用可能であることを要求します。ただし、利用できない場合、uvはPythonをダウンロードします。詳細については、Pythonバージョンのドキュメントを参照してください。

仮想環境の使用

デフォルトの仮想環境名を使用する場合、uvは後続の呼び出し中に自動的に仮想環境を見つけて使用します。

$ uv venv

$ # 新しい仮想環境にパッケージをインストールする
$ uv pip install ruff

仮想環境を「アクティブ化」して、そのパッケージを利用できるようにすることができます：

macOSおよびLinuxWindows

$ source .venv/bin/activate

$ .venv\Scripts\activate

任意のPython環境の使用

uvはPythonに依存しないため、他の仮想環境にもインストールすることができます。例えば、VIRTUAL_ENV=/path/to/venvを設定すると、uvは/path/to/venvにインストールされます。uvがインストールされている場所に関係なくです。VIRTUAL_ENVがPEP 405準拠の仮想環境でないディレクトリに設定されている場合、それは無視されます。

uvは、--python引数をuv pip syncやuv pip installに提供することで、任意の仮想環境や非仮想環境にもインストールすることができます。例えば、uv pip install --python /path/to/pythonは、/path/to/pythonインタープリタにリンクされた環境にインストールします。

便利なことに、uv pip install --systemはシステムPython環境にインストールします。--systemを使用することは、uv pip install --python $(which python)にほぼ相当しますが、仮想環境にリンクされた実行可能ファイルはスキップされることに注意してください。依存関係の管理には仮想環境の使用をお勧めしますが、--systemは継続的インテグレーションやコンテナ化された環境に適しています。

--systemフラグは、システム環境の変更を許可するためにも使用されます。例えば、--python引数を使用してPythonバージョンを指定することができます（例：--python 3.12）。uvはリクエストに応じたインタープリタを検索します。uvがシステムインタープリタ（例：/usr/lib/python3.12）を見つけた場合、この非仮想Python環境の変更を許可するために--systemフラグが必要です。--systemフラグがない場合、uvは仮想環境にないインタープリタを無視します。逆に、--systemフラグが提供されている場合、uvは仮想環境にあるインタープリタを無視します。

プラットフォームやディストリビューション全体でシステムPythonにインストールすることは非常に困難です。uvは一般的なケースをサポートしていますが、すべてのケースで動作するわけではありません。例えば、Python 3.10以前のDebianでシステムPythonにインストールすることは、ディストリビューションのdistutils（ただしsysconfigではない）のパッチ適用のためサポートされていません。仮想環境の使用を常にお勧めしますが、uvはこれらの非標準環境では仮想環境を必須と考えています。

uvがPython環境にインストールされている場合（例：pipで）、他の環境を変更するために使用することができます。ただし、python -m uvで呼び出された場合、uvは親インタープリタの環境をデフォルトで使用します。Pythonを介してuvを呼び出すと起動オーバーヘッドが追加されるため、一般的な使用にはお勧めしません。

uv自体はPythonに依存しませんが、依存関係を環境にインストールするため、およびソースディストリビューションをビルドするためにPython環境を見つける必要があります。

Python環境の検出

uv pip syncやuv pip installなどの環境を変更するコマンドを実行する際、uvは次の順序で仮想環境を検索します：

VIRTUAL_ENV環境変数に基づくアクティブな仮想環境。
CONDA_PREFIX環境変数に基づくアクティブなConda環境。
現在のディレクトリ、または最も近い親ディレクトリにある.venvの仮想環境。

仮想環境が見つからない場合、uvはuv venvを使用して現在のディレクトリに仮想環境を作成するようユーザーに促します。

--systemフラグが含まれている場合、uvは仮想環境の検索をスキップしてインストールされたPythonバージョンを検索します。同様に、uv pip compileなどの環境を変更しないコマンドを実行する場合、uvは仮想環境を必要としませんが、Pythonインタープリタは依然として必要です。インストールされたPythonバージョンの検出の詳細については、Pythonの検出のドキュメントを参照してください。