环境变量

可以将此变量设置为镜像 URL，以便从不同来源获取 PyPy 安装包。提供的 URL 将替换 https://downloads.python.org/pypy，例如 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2。也可以使用 file:// URL 方案从本地目录读取发行版。

`UV_PYTHON`

等同于 --python 命令行参数。如果设置为一个路径，uv 将在所有操作中使用此 Python 解释器。

`UV_PYTHON_DOWNLOADS`

等同于 python-downloads 设置，禁用时等同于 --no-python-downloads 选项。用于设置 uv 是否允许下载 Python。

`UV_PYTHON_DOWNLOADS_JSON_URL`

托管 Python 安装信息硬编码在 uv 二进制文件中。

可以将此变量设置为指向 JSON 的 URL，用作 Python 安装列表。这将允许设置 Python 安装的每个属性，主要是用于离线镜像的 url 部分。

请注意，目前仅支持本地路径。

`UV_PYTHON_INSTALL_MIRROR`

托管的 Python 安装包是从 Astral 的 python-build-standalone 项目下载的。

可以将此变量设置为镜像 URL，以便从不同来源获取 Python 安装包。提供的 URL 将替换 https://github.com/astral-sh/python-build-standalone/releases/download，例如，在 https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz 中。可以使用 file:// URL 方案从本地目录读取发行版。

`UV_PYTHON_PREFERENCE`

uv 应优先使用系统 Python 版本还是托管 Python 版本。

`UV_REQUEST_TIMEOUT`

HTTP 请求的超时时间（以秒为单位）。等同于 UV_HTTP_TIMEOUT。

`UV_REQUIRE_HASHES`

等同于 --require-hashes 命令行参数。如果设置为 true， uv 将要求需求文件中指定的所有依赖项都有哈希值。

`UV_RESOLUTION`

等同于 --resolution 命令行参数。例如，如果设置为 lowest-direct，uv 将安装所有直接依赖项的最低兼容版本。

`UV_STACK_SIZE`

用于设置 uv 使用的栈大小。

值的单位为字节，如果 UV_STACK_SIZE 和 RUST_MIN_STACK 均未设置，uv 将使用 4MB（4194304）的栈。UV_STACK_SIZE 优先于 RUST_MIN_STACK。

与常规的 RUST_MIN_STACK 语义不同，这可能会影响主线程的栈大小，因为我们实际上会创建自己的 main2 线程，以解决 Windows 实际主线程只有 1MB 的问题。该线程的大小为 max(UV_STACK_SIZE, 1MB)。

`UV_SYSTEM_PYTHON`

等同于 --system 命令行参数。如果设置为 true，uv 将使用系统 PATH 中找到的第一个 Python 解释器。

警告：UV_SYSTEM_PYTHON=true 适用于持续集成（CI）或容器化环境，使用时应谨慎，因为修改系统 Python 可能会导致意外行为。

`UV_TOOL_BIN_DIR`

指定用于安装工具可执行文件的 “bin” 目录。

`UV_TOOL_DIR`

指定 uv 存储托管工具的目录。

`UV_TORCH_BACKEND`

等同于 --torch-backend 命令行参数（例如 cpu、cu126 或 auto）。

`UV_UNMANAGED_INSTALL`

在诸如 CI 这样的临时环境中使用，将 uv 安装到特定路径，同时防止安装程序修改 shell 配置文件或环境变量。

`UV_VENV_SEED`

将种子包（pip、setuptools 和 wheel 中的一个或多个）安装到由 uv venv 创建的虚拟环境中。

请注意，setuptools 和 wheel 不包含在 Python 3.12 及更高版本的环境中。

外部定义的变量

uv 还会读取以下外部定义的环境变量：

`ACTIONS_ID_TOKEN_REQUEST_TOKEN`

用于通过 uv publish 进行可信发布。包含 OIDC 请求令牌。

`ACTIONS_ID_TOKEN_REQUEST_URL`

用于通过 uv publish 进行可信发布。包含 OIDC 令牌 URL。

`ALL_PROXY`

所有网络请求的通用代理。

`APPDATA`

Windows 系统上用户级配置目录的路径。

`BASH_VERSION`

用于检测是否使用 Bash shell。

`CLICOLOR_FORCE`

用于通过 anstyle 控制颜色。

`COLUMNS`

覆盖用于换行的终端宽度。uv 不会直接读取此变量。

这是一个准标准变量，例如在 ncurses(3x) 中有描述。

`CONDA_DEFAULT_ENV`

用于确定活动的 Conda 环境是否为基础环境。

`CONDA_PREFIX`

用于检测已激活的 Conda 环境。

`FISH_VERSION`

用于检测是否使用 Fish shell。

`FORCE_COLOR`

强制输出带颜色的内容，无论终端是否支持。

请参阅 force-color.org。

`GITHUB_ACTIONS`

用于通过 uv publish 进行可信发布。

`HOME`

标准的 HOME 环境变量。

`HTTPS_PROXY`

HTTPS 请求的代理。

`HTTP_PROXY`

HTTP 请求的代理。

`HTTP_TIMEOUT`

HTTP 请求的超时时间（以秒为单位）。等同于 UV_HTTP_TIMEOUT。

`INSTALLER_NO_MODIFY_PATH`

使用独立安装程序和 self update 功能安装 uv 时，避免修改 PATH 环境变量。

`JPY_SESSION_NAME`

用于检测是否在 Jupyter 笔记本中运行。

`KSH_VERSION`

用于检测是否使用 Ksh shell。

`LOCALAPPDATA`

用于查找 Microsoft Store 安装的 Python。

`MACOSX_DEPLOYMENT_TARGET`

与 --python-platform macos 及相关变体一起使用，以设置部署目标（即支持的最低 macOS 版本）。

默认值为 13.0，这是编写本文时最新的非终止支持的 macOS 版本。

`NETRC`

用于设置 .netrc 文件的位置。

`NO_COLOR`

禁用带颜色的输出（优先于 FORCE_COLOR）。

请参阅 no-color.org。

`NU_VERSION`

用于检测是否使用 NuShell。

标准的 PAGER posix 环境变量。uv 使用它来配置合适的分页器。

`PATH`

标准的 PATH 环境变量。

`PROMPT`

用于检测是否使用 Windows 命令提示符（与 PowerShell 相对）。

`PWD`

标准的 PWD posix 环境变量。

`PYC_INVALIDATION_MODE`

使用 --compile 运行时要使用的验证模式。

请参阅 PycInvalidationMode。

`PYTHONPATH`

将目录添加到 Python 模块搜索路径（例如，PYTHONPATH=/path/to/modules）。

`RUST_LOG`

如果设置了该环境变量，uv 将使用此值作为其 --verbose 输出的日志级别。接受任何与 tracing_subscriber 库兼容的过滤器。

例如： * RUST_LOG=uv=debug 等同于在命令行中添加 --verbose。 * RUST_LOG=trace 将启用跟踪级别的日志记录。

更多信息请参阅 tracing 文档。

`RUST_MIN_STACK`

用于设置 uv 使用的栈大小。

该值以字节为单位，如果 UV_STACK_SIZE 和 RUST_MIN_STACK 均未设置，uv 将使用 4MB（4194304）的栈。UV_STACK_SIZE 优先于 RUST_MIN_STACK。

建议设置 UV_STACK_SIZE，因为 RUST_MIN_STACK 也会影响子进程，例如使用 Rust 代码的构建后端。

与常规的 RUST_MIN_STACK 语义不同，这可能会影响主线程的栈大小，因为我们实际上会生成自己的 main2 线程，以解决 Windows 真实主线程只有 1MB 的问题。该线程的大小为 max(RUST_MIN_STACK, 1MB)。

如果可执行文件是通过符号链接调用的，某些平台将返回符号链接的路径，而其他平台将返回符号链接目标的路径。

有关安全注意事项，请参阅 https://doc.rust-lang.org/std/env/fn.current_exe.html#security。