Skip to content

Python environments#

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

Creating a virtual environment#

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

$ uv venv

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

$ uv venv my-name

例えば、Python 3.11で仮想環境を作成するために、Pythonバージョンを要求することができる。:

$ uv venv --python 3.11

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

Using a virtual environment#

デフォルトのバーチャル環境名を使用すると、uvは自動的にバーチャル環境を検索し、その後の呼び出しで使用します。

$ uv venv

$ # Install a package in the new virtual environment
$ uv pip install ruff

仮想環境を「アクティブ化」して、そのパッケージを使用可能にすることができます。:

macOS and Linux
$ source .venv/bin/activate
Windows
$ .venv\Scripts\activate

Using arbitrary Python environments#

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

uvは、uv pip syncまたはuv pip installに--python引数を指定することで、任意の非仮想環境にもインストールできます。たとえば、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へのインストールは、distribution's patching of distutils (but not sysconfig)のためにサポートされていません。私たちは常に仮想環境の使用を推奨していますが、uvはこれらの非標準環境では仮想環境が必要であると考えています。

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

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

Discovery of Python environments#

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 discoveryのドキュメントを参照してください。