Using Python environmentsPython環境の使用

Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike pip, uv requires using a virtual environment by default.各Pythonインストールには、Pythonが使用されるときにアクティブな環境があります。パッケージは環境にインストールされ、Pythonスクリプトからそのモジュールを利用できるようになります。一般的に、Pythonインストールの環境を変更しないことがベストプラクティスとされています。これは、パッケージを自動的に管理することが多いオペレーティングシステムに付属するPythonインストールにとって特に重要です。仮想環境は、Pythonインストールの環境からパッケージを隔離する軽量な方法です。pipとは異なり、uvはデフォルトで仮想環境を使用する必要があります。

Creating a virtual environment仮想環境の作成

uv supports creating virtual environments, e.g., to create a virtual environment at .venv:uvは仮想環境の作成をサポートしています。例えば、.venvに仮想環境を作成するには:

$ uv venv

A specific name or path can be specified, e.g., to create a virtual environment at my-name:特定の名前やパスを指定することができます。例えば、my-nameに仮想環境を作成するには:

$ uv venv my-name

A Python version can be requested, e.g., to create a virtual environment with Python 3.11:Pythonのバージョンをリクエストすることができます。例えば、Python 3.11で仮想環境を作成するには:

$ uv venv --python 3.11

Note this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the Python version documentation for more details.これは、要求されたPythonバージョンがシステムに存在する必要があることに注意してください。しかし、利用できない場合、uvはあなたのためにPythonをダウンロードします。詳細については、Pythonバージョンのドキュメントを参照してください。

Using a virtual environment仮想環境の使用

When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations.デフォルトの仮想環境名を使用する場合、uvは自動的に仮想環境を見つけて、次回の呼び出し時に使用します。

$ uv venv

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

The virtual environment can be "activated" to make its packages available:仮想環境は、そのパッケージを利用できるように「アクティブ化」できます:

macOS and LinuxWindows

$ source .venv/bin/activate

PS> .venv\Scripts\activate

Note注意

The default activation script on Unix is for POSIX compliant shells like sh, bash, or zsh. There are additional activation scripts for common alternative shells.Unixのデフォルトのアクティベーションスクリプトは、sh、bash、またはzshのようなPOSIX準拠のシェル用です。 一般的な代替シェル用の追加のアクティベーションスクリプトがあります。

fishcsh / tcshNushell

$ source .venv/bin/activate.fish

$ source .venv/bin/activate.csh

$ use .venv\Scripts\activate.nu

Deactivating an environment環境の非アクティブ化

To exit a virtual environment, use the deactivate command:仮想環境を終了するには、deactivateコマンドを使用します：

$ deactivate

Using arbitrary Python environments任意のPython環境の使用

Since uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting VIRTUAL_ENV=/path/to/venv will cause uv to install into /path/to/venv, regardless of where uv is installed. Note that if VIRTUAL_ENV is set to a directory that is not a PEP 405 compliant virtual environment, it will be ignored.uvはPythonに依存しないため、自身以外の仮想環境にインストールできます。 例えば、VIRTUAL_ENV=/path/to/venvを設定すると、uvは/path/to/venvにインストールされます。 uvがどこにインストールされているかに関係なく、VIRTUAL_ENVが ではないディレクトリに設定されている場合、 PEP 405準拠の仮想環境として無視されます。

uv can also install into arbitrary, even non-virtual environments, with the --python argument provided to uv pip sync or uv pip install. For example, uv pip install --python /path/to/python will install into the environment linked to the /path/to/python interpreter.uvは、--python引数をuv pip syncまたはuv pip installに提供することで、任意の、さらには非仮想環境にもインストールできます。例えば、 uv pip install --python /path/to/pythonは、 /path/to/pythonインタープリタにリンクされた環境にインストールされます。

For convenience, uv pip install --system will install into the system Python environment. Using --system is roughly equivalent to uv pip install --python $(which python), but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, --system is appropriate in continuous integration and containerized environments.便利なことに、uv pip install --systemはシステムPython環境にインストールします。 --systemを使用することは、uv pip install --python $(which python)とほぼ同等ですが、 仮想環境にリンクされた実行可能ファイルはスキップされることに注意してください。 依存関係管理には一般的に仮想環境の使用を推奨していますが、--systemは継続的インテグレーションやコンテナ化された環境では適切です。

The --system flag is also used to opt in to mutating system environments. For example, the --python argument can be used to request a Python version (e.g., --python 3.12), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., /usr/lib/python3.12), then the --system flag is required to allow modification of this non-virtual Python environment. Without the --system flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the --system flag is provided, uv will ignore any interpreters that are in virtual environments.--systemフラグは、システム環境の変更を選択するためにも使用されます。例えば、 --python引数を使用してPythonのバージョンを要求できます（例：--python 3.12）。uvは リクエストを満たすインタープリタを検索します。uvがシステムインタープリタ（例： /usr/lib/python3.12）を見つけた場合、--systemフラグが必要で、 この非仮想Python環境の変更を許可します。--systemフラグがない場合、uvは 仮想環境にないインタープリタを無視します。逆に、--systemフラグが提供されると、uvは 仮想環境にあるインタープリタを無視します。

Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the distribution's patching of distutils (but not sysconfig). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments.プラットフォームやディストリビューションを超えてシステムPythonにインストールすることは非常に難しいです。uvは 一般的なケースをサポートしていますが、すべてのケースで機能するわけではありません。例えば、Python 3.10以前のDebianにシステム Pythonにインストールすることは、 ディストリビューションのdistutils（ただしsysconfigではない）へのパッチのためにサポートされていません。 私たちは常に仮想環境の使用を推奨していますが、uvはこれらの非標準環境ではそれらが必要であると考えています。

If uv is installed in a Python environment, e.g., with pip, it can still be used to modify other environments. However, when invoked with python -m uv, uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage.uvがPython環境にインストールされている場合、例えばpipで、他の環境を変更するために使用できます。 ただし、python -m uvで呼び出すと、uvは親インタープリタの環境を使用することがデフォルトになります。 Python経由でuvを呼び出すと、起動オーバーヘッドが追加され、一般的な使用には推奨されません。

uv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions.uv自体はPythonに依存しませんが、(1) 環境に依存関係をインストールし、(2) ソース配布をビルドするためにPython環境を見つける必要があります。

Discovery of Python environmentsPython環境の発見

When running a command that mutates an environment such as uv pip sync or uv pip install, uv will search for a virtual environment in the following order:環境を変更するコマンド（例えば、uv pip syncやuv pip install）を実行する際、uvは次の順序で仮想環境を検索します：

• An activated virtual environment based on the VIRTUAL_ENV environment variable.VIRTUAL_ENV環境変数に基づくアクティブな仮想環境。
• An activated Conda environment based on the CONDA_PREFIX environment variable.CONDA_PREFIX環境変数に基づくアクティブなConda環境。
• A virtual environment at .venv in the current directory, or in the nearest parent directory.現在のディレクトリまたは最も近い親ディレクトリにある.venvの仮想環境。

If no virtual environment is found, uv will prompt the user to create one in the current directory via uv venv.仮想環境が見つからない場合、uvはユーザーに対して現在のディレクトリに仮想環境を作成するように促します（uv venvを使用）。

If the --system flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as uv pip compile, uv does not require a virtual environment — however, a Python interpreter is still required. See the documentation on Python discovery for details on the discovery of installed Python versions.もし--systemフラグが含まれている場合、uvはインストールされたPythonバージョンのための仮想環境の検索をスキップします。同様に、環境を変更しないコマンド（例えば、uv pip compile）を実行する際、uvは仮想環境を必要としません — ただし、Pythonインタープリタは依然として必要です。インストールされたPythonバージョンの発見に関する詳細は、Pythonの発見に関するドキュメントを参照してください。