4.1 使用环境

  3 分钟阅读  

原文链接: https://docs.astral.sh/uv/pip/environments/

4.1 使用环境

每个 Python 安装都有一个在使用 Python 时激活的环境。可以把包安装到某个环境中，使它们的模块可以从你的 Python 脚本中使用。通常认为，最好不要修改 Python 安装的环境。对随操作系统提供的 Python 安装来说尤其重要，它们往往自行管理包。虚拟环境是一种轻量的方式，用于把包与 Python 安装的环境隔离。与 pip 不同，uv 默认要求使用虚拟环境。

创建虚拟环境

uv 支持创建虚拟环境，例如在 .venv 处创建虚拟环境：

1

$ uv venv

可以指定名称或路径，例如在 my-name 处创建虚拟环境：

1

$ uv venv my-name

可以请求 Python 版本，例如用 Python 3.11 创建虚拟环境：

1

$ uv venv --python 3.11

注意这要求所请求的 Python 版本在系统中可用。不过如果不可用，uv 会为你下载 Python。更多细节请参阅 Python 版本文档。

使用虚拟环境

使用默认虚拟环境名称时，uv 会在后续调用中自动找到并使用该虚拟环境。

1
2
3
4

$ uv venv

$ # 在新的虚拟环境中安装一个包
$ uv pip install ruff

虚拟环境可以被“激活”，从而让其中的包可用：

1

$ source .venv/bin/activate

1

PS> .venv\Scripts\activate

注意

Unix 上的默认激活脚本面向符合 POSIX 的 shell，例如 sh、bash 或 zsh。常见替代 shell 还有额外的激活脚本。

> > > > > > > >
1

$ source .venv/bin/activate.fish

1

$ source .venv/bin/activate.csh

1

$ use .venv\Scripts\activate.nu

停用环境

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

1

$ deactivate

使用任意 Python 环境

由于 uv 不依赖 Python，它可以安装到自身之外的虚拟环境。例如，设置 VIRTUAL_ENV=/path/to/venv 会让 uv 安装到 /path/to/venv，无论 uv 本身安装在哪里。注意如果 VIRTUAL_ENV 指向的目录不是符合 PEP 405 的虚拟环境，它会被忽略。

uv 也可以通过 --python 选项安装到任意的、甚至非虚拟的环境。例如 uv pip install --python /path/to/python 会安装到与 /path/to/python 解释器关联的环境中，无论它是不是虚拟环境。--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 支持常见情况，但并非所有情况都能工作。例如，在 Python 3.10 之前的 Debian 上安装到系统 Python 是不受支持的，因为该发行版对 distutils（而非 sysconfig）打了补丁。虽然我们始终建议使用虚拟环境，但在这些非标准环境中 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 发现文档。

最后修改 September 25, 2026: 更新 (221c74c33)