跳到内容

使用 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

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

可以“激活”虚拟环境以使其软件包可用

$ source .venv/bin/activate

PS> .venv\Scripts\activate

注意

Unix 上的默认激活脚本适用于 POSIX 兼容的 shell，如 sh、bash 或 zsh。还有一些适用于常见替代 shell 的附加激活脚本。

$ source .venv/bin/activate.fish

$ source .venv/bin/activate.csh

$ use .venv\Scripts\activate.nu

停用环境

要退出虚拟环境，请使用 deactivate 命令

$ deactivate

使用任意 Python 环境

由于 uv 不依赖于 Python，它可以安装到其他虚拟环境，而不是它自己的环境。例如，设置 VIRTUAL_ENV=/path/to/venv 将导致 uv 安装到 /path/to/venv，而不管 uv 安装在哪里。请注意，如果 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），则需要 --system 标志以允许修改此非虚拟 Python 环境。如果没有 --system 标志，uv 将忽略任何不在虚拟环境中的解释器。相反，当提供 --system 标志时，uv 将忽略任何 在 虚拟环境中的解释器。

跨平台和发行版安装到系统 Python 非常困难。uv 支持常见情况，但并非在所有情况下都有效。例如，由于 发行版对 distutils（而不是 sysconfig）的修补，不支持在 Python 3.10 之前的 Debian 上安装到系统 Python。虽然我们始终建议使用虚拟环境，但 uv 认为它们在这些非标准环境中是必需的。

如果 uv 安装在 Python 环境中，例如使用 pip，它仍然可以用于修改其他环境。但是，当使用 python -m uv 调用时，uv 将默认使用父解释器的环境。通过 Python 调用 uv 会增加启动开销，不建议用于一般用途。

uv 本身不依赖于 Python，但它确实需要定位 Python 环境才能 (1) 将依赖项安装到环境中和 (2) 构建源分发。

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 发现的文档。