环境变量

此变量可以设置为镜像 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`

添加于 0.1.40

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

`UV_PYTHON_BIN_DIR`

添加于 0.4.29

指定放置已安装、管理的 Python 可执行文件链接的目录。

`UV_PYTHON_CACHE_DIR`

添加于 0.7.0

指定在安装前用于缓存已管理 Python 安装存档的目录。

`UV_PYTHON_CPYTHON_BUILD`

添加于 0.8.14

将管理的 CPython 版本固定为特定构建版本。

对于 CPython，这应该是构建日期（例如“20250814”）。

`UV_PYTHON_DOWNLOADS`

添加于 0.3.2

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

`UV_PYTHON_DOWNLOADS_JSON_URL`

添加于 0.6.13

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

此变量可以设置为指向 Python 安装 JSON 列表的本地路径或 URL，以覆盖硬编码的列表。

这允许自定义下载 URL，或者使用比此版本 uv 中硬编码的 Python 版本稍旧或稍新的版本。

`UV_PYTHON_GRAALPY_BUILD`

添加于 0.8.14

将管理的 GraalPy 版本固定为特定构建版本。

对于 GraalPy，这应该是 GraalPy 版本（例如“24.2.2”）。

`UV_PYTHON_INSTALL_BIN`

添加于 0.8.0

是否将 Python 可执行文件安装到 UV_PYTHON_BIN_DIR 目录中。

`UV_PYTHON_INSTALL_MIRROR`

添加于 0.2.35

管理的 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_INSTALL_REGISTRY`

添加于 0.8.0

是否将 Python 可执行文件安装到 Windows 注册表中。

`UV_PYTHON_PREFERENCE`

添加于 0.3.2

uv 是否应优先使用系统或管理的 Python 版本。

`UV_PYTHON_PYODIDE_BUILD`

添加于 0.8.14

将管理的 Pyodide 版本固定为特定构建版本。

对于 Pyodide，这应该是 Pyodide 版本（例如“0.28.1”）。

`UV_PYTHON_PYPY_BUILD`

添加于 0.8.14

将管理的 PyPy 版本固定为特定构建版本。

对于 PyPy，这应该是 PyPy 版本（例如“7.3.20”）。

`UV_REQUEST_TIMEOUT`

添加于 0.1.6

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

`UV_REQUIRE_HASHES`

添加于 0.1.34

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

`UV_RESOLUTION`

添加于 0.1.27

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

`UV_S3_ENDPOINT_URL`

添加于 0.8.21

要作为 S3 兼容存储端点处理的 URL。对此端点的请求将基于 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_PROFILE 和 AWS_CONFIG_FILE 环境变量，使用 AWS Signature Version 4 进行签名。

`UV_SKIP_WHEEL_FILENAME_CHECK`

添加于 0.8.23

安装 wheel 时避免校验 wheel 文件名与其内容是否匹配。不建议这样做，因为文件名不一致的 wheel 应被视为无效，并由相关包维护者更正；但是，在极少数情况下，此选项可用于解决无效构件的问题。

`UV_STACK_SIZE`

添加于 0.0.5

用于设置 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`

添加于 0.1.18

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

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

`UV_TEST_NO_HTTP_RETRY_DELAY`

添加于 0.7.21

用于在测试中禁用 HTTP 重试的延迟。

`UV_TOOL_BIN_DIR`

添加于 0.3.0

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

`UV_TOOL_DIR`

添加于 0.2.16

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

`UV_TORCH_BACKEND`

添加于 0.6.9

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

`UV_UNMANAGED_INSTALL`

添加于 0.5.0

用于 CI 等临时环境，将 uv 安装到特定路径，同时防止安装程序修改 shell 配置文件或环境变量。

`UV_UPLOAD_HTTP_TIMEOUT`

添加于 0.9.1

仅针对上传 HTTP 请求的超时时间（以秒为单位）。（默认：900秒）

`UV_VENV_CLEAR`

添加于 0.8.0

等同于命令行参数 --clear。如果设置，uv 将删除目标路径中任何现有的文件或目录。

`UV_VENV_RELOCATABLE`

添加于 0.10.8

等同于命令行参数 --relocatable。如果设置，虚拟环境将是可重新定位的。

`UV_VENV_SEED`

添加于 0.5.21

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

请注意，Python 3.12+ 环境中不包含 setuptools 和 wheel。

`UV_WORKING_DIR`

添加于 下一个版本

等同于命令行参数 --directory。UV_WORKING_DIRECTORY (添加于 v0.9.1) 也作为别名受支持，以实现向后兼容。

外部定义的变量

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

`ALL_PROXY`

添加于 0.1.38

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

`ANDROID_API_LEVEL`

添加于 0.8.16

与 --python-platform aarch64-linux-android 及相关变体一起使用，以设置 Android API 级别。（即最低支持的 Android API 级别）。

默认为 24。

`APPDATA`

添加于 0.1.42

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

`AWS_ACCESS_KEY_ID`

添加于 0.8.21

签名 S3 请求时使用的 AWS 访问密钥 ID。

`AWS_CONFIG_FILE`

添加于 0.8.21

签名 S3 请求时使用的 AWS 配置文件。

`AWS_DEFAULT_REGION`

添加于 0.8.21

如果未设置 AWS_REGION，则签名 S3 请求时使用的默认 AWS 区域。

`AWS_PROFILE`

添加于 0.8.21

签名 S3 请求时使用的 AWS 配置概要文件。

`AWS_REGION`

添加于 0.8.21

签名 S3 请求时使用的 AWS 区域。

`AWS_SECRET_ACCESS_KEY`

添加于 0.8.21

签名 S3 请求时使用的 AWS 私有访问密钥。

`AWS_SESSION_TOKEN`

添加于 0.8.21

签名 S3 请求时使用的 AWS 会话令牌。

`AWS_SHARED_CREDENTIALS_FILE`

添加于 0.8.21

签名 S3 请求时使用的 AWS 共享凭据文件。

`BASH_VERSION`

添加于 0.1.28

用于检测 Bash shell 的使用情况。

`CLICOLOR_FORCE`

添加于 0.1.32

用于通过 anstyle 控制颜色。

`COLUMNS`

添加于 0.6.2

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

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

`CONDA_DEFAULT_ENV`

添加于 0.5.0

用于确定活动 Conda 环境的名称。

`CONDA_PREFIX`

添加于 0.0.5

用于检测活动 Conda 环境的路径。

`DEPENDABOT`

添加于 0.9.11

用于确定我们是否在 Dependabot 中运行。

`FISH_VERSION`

添加于 0.1.28

用于检测 Fish shell 的使用情况。

`FORCE_COLOR`

添加于 0.2.7

无论终端是否支持，强制彩色输出。

请参阅 force-color.org。

`GITHUB_ACTIONS`

添加于 0.4.16

表明当前进程正在 GitHub Actions 中运行。

当设置为 true 时，uv publish 可能会尝试可信发布流程。

`GITLAB_CI`

添加于 0.8.18

表明当前进程正在 GitLab CI 中运行。

当设置为 true 时，uv publish 可能会尝试可信发布流程。

`HF_TOKEN`

添加于 0.8.1

Hugging Face 请求的身份验证令牌。当设置时，uv 在向 https://hugging-face.cn/ 及其任何子域发出请求时将使用此令牌。

`HOME`

添加于 0.0.5

标准的 HOME 环境变量。

`HTTPS_PROXY`

添加于 0.1.38

HTTPS 请求的代理。

`HTTP_PROXY`

添加于 0.1.38

HTTP 请求的代理。

`HTTP_TIMEOUT`

添加于 0.1.7

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

`IPHONEOS_DEPLOYMENT_TARGET`

添加于 0.8.16

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

默认为 13.0。

`JPY_SESSION_NAME`

添加于 0.2.6

用于检测何时在 Jupyter 笔记本中运行。

`KSH_VERSION`

添加于 0.2.33

用于检测 Ksh shell 的使用情况。

`LOCALAPPDATA`

添加于 0.3.3

用于查找 Microsoft Store Python 安装。

`MACOSX_DEPLOYMENT_TARGET`

添加于 0.1.42

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

默认为 13.0（撰写本文时，非 EOL 的 macOS 版本中最旧的版本）。

`NETRC`

添加于 0.1.16

用于设置 .netrc 文件位置。

`NO_COLOR`

添加于 0.2.7

禁用彩色输出（优先级高于 FORCE_COLOR）。

请参阅 no-color.org。

`NO_PROXY`

添加于 0.1.38

主机名（例如 example.com）和/或模式（例如 192.168.1.0/24）的逗号分隔列表，这些应绕过代理。

`NU_VERSION`

添加于 0.1.16

用于检测 NuShell 的使用情况。

添加于 0.4.18

标准的 PAGER posix 环境变量。由 uv 用于配置适当的分页器。

`PATH`

添加于 0.0.5

标准的 PATH 环境变量。

`PROMPT`

添加于 0.1.16

用于检测 Windows 命令提示符的使用情况（相对于 PowerShell）。

`PSModulePath`

添加于 下一个版本

用于检测 PowerShell 的使用情况（由所有平台上的 PowerShell 设置）。

`PWD`

添加于 0.0.5

标准的 PWD posix 环境变量。

`PYC_INVALIDATION_MODE`

添加于 0.1.7

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

请参阅 PycInvalidationMode。

`PYTHONPATH`

添加于 0.1.22

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

`PYX_API_KEY`

添加于 0.8.15

pyx API 密钥（例如 sk-pyx-...）。

`PYX_API_URL`

添加于 0.8.15

pyx Simple API 服务器的 URL。

`PYX_AUTH_TOKEN`

添加于 0.8.15

pyx 身份验证令牌（例如 eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...），由 uv auth token 输出。

`PYX_CDN_DOMAIN`

添加于 0.8.15

pyx CDN 的域名。

`PYX_CREDENTIALS_DIR`

添加于 0.8.15

指定 uv 存储 pyx 凭据的目录。

`RUST_BACKTRACE`

添加于 0.7.22

如果设置，它可用于在发生 panic 时显示更多堆栈跟踪详细信息。这在 Windows 上被 uv 特别使用，以在平台异常期间显示更多详细信息。

例如

RUST_BACKTRACE=1 将打印简短的堆栈跟踪。
RUST_BACKTRACE=full 将打印完整的堆栈跟踪。

请参阅 Rust 堆栈跟踪文档以获取更多信息。

`RUST_LOG`

添加于 0.0.5

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

例如

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

请参阅 tracing 文档以获取更多信息。

`RUST_MIN_STACK`

添加于 0.5.19

用于设置 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)。

`SHELL`

添加于 0.1.16

标准的 SHELL posix 环境变量。

`SSL_CERT_DIR`

添加于 0.9.10

用于 SSL 连接的证书包的自定义路径。支持使用特定于平台的定界符（Unix 上为 :，Windows 上为 ;）分隔的多个条目。

设置时，优先级高于 UV_NATIVE_TLS。

`SSL_CERT_FILE`

添加于 0.1.14

用于 SSL 连接的自定义证书包文件路径。

设置时，优先级高于 UV_NATIVE_TLS。

这会传播给 uv 派生的所有子进程。

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

请参阅 https://doc.rust-lang.net.cn/std/env/fn.current_exe.html#security 以获取安全性考虑。