uv - 配置 [官方文档翻译]

伊织code2025-03-25 23:27

文章目录

配置概述

https://docs.astral.sh/uv/configuration/

阅读有关配置uv的各种方法

或者，跳转到设置参考，其中列出了可用的配置选项。

配置文件

uv 支持在项目和用户级别的持久配置文件。

具体来说，uv 将在当前目录或最近的父目录中搜索 pyproject.toml 或 uv.toml 文件。

注意：对于 tool 命令，这些命令在用户级别运行，将忽略本地配置文件。相反，uv 将仅从用户级别配置（例如，~/.config/uv/uv.toml）和系统级别配置（例如，/etc/uv/uv.toml）中读取。

在工作区中，uv 将从工作区根目录开始搜索，忽略在工作区成员中定义的任何配置。由于工作区作为一个单一单元被锁定，配置在所有成员之间是共享的。

如果找到 pyproject.toml 文件，uv 将会从 [tool.uv] 表格中读取配置。例如，要设置一个持久的索引 URL，请将以下内容添加到 pyproject.toml 文件中：
pyproject.toml

yaml 复制代码 
[[tool.uv.index]]
url = "https://test.pypi.org/simple"
default = true

（如果不存在这样的表，则将忽略 pyproject.toml 文件，uv 将继续在目录层次结构中搜索。）

uv 还会搜索 uv.toml 文件，这些文件遵循相同的结构，但省略了 [tool.uv] 前缀。例如：
uv.toml

yaml 复制代码 
[[index]]
url = "https://test.pypi.org/simple"
default = true

注意：uv.toml 文件比 pyproject.toml 文件具有优先级，因此如果目录中同时存在 uv.toml 和 pyproject.toml 文件，配置将从 uv.toml 中读取，并且将忽略伴随的 pyproject.toml 中的 [tool.uv] 部分。

uv 还将在 macOS 和 Linux 上在 ~/.config/uv/uv.toml (或 $XDG_CONFIG_HOME/uv/uv.toml)，或在 Windows 上的 %APPDATA%\uv\uv.toml 处发现用户级别的配置；以及 macOS 和 Linux 上的 /etc/uv/uv.toml (或 $XDG_CONFIG_DIRS/uv/uv.toml)，或在 Windows 上的 %SYSTEMDRIVE%\ProgramData\uv\uv.toml 处的系统级别配置。

用户和系统级别的配置必须使用 uv.toml 格式，而不是 pyproject.toml 格式，因为 pyproject.toml 的目的是定义一个 Python 项目。

如果找到项目级、用户级和系统级的配置文件，设置将合并，项目级配置优先于用户级配置，用户级配置优先于系统级配置。（如果在多个系统级配置文件中找到，例如在 /etc/uv/uv.toml 和 $XDG_CONFIG_DIRS/uv/uv.toml 中，只使用第一个找到的文件，其中 XDG 优先。）

例如，如果一个字符串、数字或布尔值同时存在于项目和用户级配置表中，则将使用项目级值，并忽略用户级值。如果两个表中都存在数组，则将数组连接起来，项目级设置将出现在合并数组的开头。

设置通过环境变量提供时，将优先于持久性配置，而通过命令行提供的设置将优先于两者。

uv接受一个--no-config命令行参数，当提供时，将禁用任何持久配置的发现。

uv 也接受一个 --config-file 命令行参数，该参数接受一个指向 uv.toml 的路径，用作配置文件。当提供时，此文件将替代 任何 发现的配置文件（例如，用户级别的配置将被忽略）。

设置

查看可用的设置的枚举，请参阅设置参考。

.env

uv run 可以从 dotenv 文件（例如，.env, .env.local, .env.development）中加载环境变量，由 dotenvy crate 提供。

要从专用位置加载 .env 文件，设置 UV_ENV_FILE 环境变量，或将 --env-file 标志传递给 uv run。

例如，要从当前工作目录中的 .env 文件加载环境变量：

复制代码
shell 复制代码 
$ echo "MY_VAR='Hello, world!'" > .env
$ uv run --env-file .env -- python -c 'import os; print(os.getenv("MY_VAR"))'
Hello, world!

--env-file 标志可以多次提供，后续文件将覆盖之前文件中定义的值。要通过 UV_ENV_FILE 环境变量提供多个文件，请使用空格分隔路径（例如，UV_ENV_FILE="/path/to/file1 /path/to/file2"）。

要禁用dotenv加载（例如，要覆盖UV_ENV_FILE或--env-file命令行参数），请将UV_NO_ENV_FILE环境变量设置为1，或将--no-env-file标志传递给uv run。

如果相同的变量在环境和 .env 文件中定义，环境中的值将具有优先权。

配置 pip 接口

提供了一个专门的工具.uv.pip部分，用于仅配置uv pip命令行接口。此部分的设置不会应用于uv命名空间之外的uv命令。然而，此部分中的许多设置在顶级命名空间中也有对应项，这些对应项会应用于uv pip接口，除非它们在uv.pip部分被覆盖。

uv.pip设置旨在与pip的接口紧密一致，并且单独声明，以保持兼容性，同时允许全局设置使用不同的设计（例如，--no-build）。

例如，在[tool.uv.pip]下设置index-url，如下所示的pyproject.toml，将仅影响uv pip子命令（例如，uv pip install，但不包括uv sync、uv lock或uv run）：

pyproject.toml

yaml 复制代码 
[tool.uv.pip]
index-url = "https://test.pypi.org/simple"

环境变量

uv 定义并尊重以下环境变量：

UV_BREAK_SYSTEM_PACKAGES

等同于 --break-system-packages 命令行参数。如果设置为 true，uv 将允许安装与系统已安装的包冲突的包。

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

UV_BUILD_CONSTRAINT

等同于命令行参数 --build-constraint。如果设置，uv 将使用此文件作为任何源分布构建的约束。使用空格分隔的文件列表。

UV_CACHE_DIR

等同于 --cache-dir 命令行参数。如果设置，uv 将使用此目录进行缓存，而不是默认的缓存目录。

UV_COMPILE_BYTECODE

等同于 --compile-bytecode 命令行参数。如果设置，uv 在安装后将编译 Python 源文件到字节码。

UV_CONCURRENT_BUILDS

设置 uv 在任何给定时间点同时构建的最大源分布数量。

UV_CONCURRENT_DOWNLOADS

设置 uv 在任何给定时间将执行的最多并发下载数量。

UV_CONCURRENT_INSTALLS

控制安装和解压包时使用的线程数。

UV_CONFIG_FILE

等同于 --config-file 命令行参数。期望一个指向本地 uv.toml 文件的路径，用作配置文件。

UV_CONSTRAINT

等同于命令行参数 --constraint。如果设置，uv 将使用此文件作为约束文件。使用空格分隔的文件列表。

UV_CUSTOM_COMPILE_COMMAND

等同于命令行参数 --custom-compile-command。

用于覆盖由 uv pip compile 生成的 requirements.txt 文件输出头中的 uv。旨在用于从包装脚本中调用 uv pip compile 的情况，以便在输出文件中包含包装脚本的名称。

UV_DEFAULT_INDEX

等同于 --default-index 命令行参数。如果设置，uv 将使用此 URL 作为默认索引，在搜索包时使用。

UV_ENV_FILE

从执行 uv run 命令时加载环境变量的 .env 文件。

UV_EXCLUDE_NEWER

等同于 --exclude-newer 命令行参数。如果设置，uv 将排除在指定日期之后发布的分发版。

UV_EXTRA_INDEX_URL

等同于 --extra-index-url 命令行参数。如果设置，uv 将使用这个以空格分隔的 URL 列表作为搜索包时的附加索引。（已弃用：请使用 UV_INDEX 代替。）

等同于 --find-links 命令行参数。如果设置，uv 将使用这个逗号分隔的附加位置列表来搜索包。

UV_FORK_STRATEGY

等同于 --fork-strategy 参数。控制通用解析期间版本选择。

UV_FROZEN

等同于命令行参数 --frozen。如果设置，uv 将在没有更新 uv.lock 文件的情况下运行。

UV_GITHUB_TOKEN

等同于 self update 的 --token 参数。用于身份验证的 GitHub 令牌。

UV_GIT_LFS

启用在从 Git 仓库安装软件包时获取存储在 Git LFS 中的文件。

UV_HTTP_TIMEOUT

HTTP 请求的超时时间（以秒为单位）。（默认：30 秒）

UV_INDEX

等同于 --index 命令行参数。如果设置，uv 将使用这个以空格分隔的 URL 列表作为额外的索引，在搜索软件包时使用。

UV_INDEX_STRATEGY

等同于命令行参数 --index-strategy。

例如，如果设置为 unsafe-any-match，uv 将考虑所有索引 URL 上给定软件包的版本，而不是将其搜索限制在包含该软件包的第一个索引 URL 上。

UV_INDEX_URL

等同于 --index-url 命令行参数。如果设置，uv 将使用此 URL 作为默认索引，在搜索包时使用。（已弃用：请使用 UV_DEFAULT_INDEX 代替。）

UV_INDEX_{name}_PASSWORD

提供名为索引的HTTP基本认证密码。

name参数是索引的名称。例如，给定一个名为foo的索引，环境变量键将是UV_INDEX_FOO_PASSWORD。

UV_INDEX_{name}_USERNAME

提供名为索引的HTTP基本认证用户名。

name参数是索引的名称。例如，给定一个名为foo的索引，环境变量键将是UV_INDEX_FOO_USERNAME。

UV_INSECURE_HOST

等同于 --allow-insecure-host 参数。

UV_INSTALLER_GHE_BASE_URL

从该URL下载uv使用独立安装程序和self update功能，代替默认的GitHub Enterprise URL。

UV_INSTALLER_GITHUB_BASE_URL

从该 URL 下载 uv 使用独立安装程序和 self update 功能，而不是默认的 GitHub URL。

UV_INSTALL_DIR

使用独立安装程序和 self update 功能安装 uv 的目录。默认为 ~/.local/bin。

UV_KEYRING_PROVIDER

等同于 --keyring-provider 命令行参数。如果设置，uv 将使用此值作为密钥环提供者。

等同于 --link-mode 命令行参数。如果设置了，uv 将使用此作为链接模式。

UV_LOCKED

等同于 --locked 命令行参数。如果设置，uv 将断言 uv.lock 保持不变。

UV_LOG_CONTEXT

为日志消息添加额外的上下文和结构。

如果未启用日志记录，例如使用 RUST_LOG 或 -v，则此操作无效果。

UV_MANAGED_PYTHON

需要使用 uv-managed Python 版本。

UV_NATIVE_TLS

等同于 --native-tls 命令行参数。如果设置为 true，uv 将使用系统的信任存储而不是捆绑的 webpki-roots 载件包。

UV_NO_BINARY

等同于 --no-binary 命令行参数。如果设置，uv 将从源代码安装所有软件包。如果可用，解析器仍然会使用预构建的 wheel 文件来提取软件包元数据。

UV_NO_BINARY_PACKAGE

等同于 --no-binary-package 命令行参数。如果设置，uv 将不会为给定的空格分隔的包列表使用预构建的 wheel。

UV_NO_BUILD

等同于 --no-build 命令行参数。如果设置，uv 将不会构建源分发版。

UV_NO_BUILD_ISOLATION

等同于 --no-build-isolation 命令行参数。如果设置，uv 将在构建源分发时跳过隔离。

UV_NO_BUILD_PACKAGE

等同于 --no-build-package 命令行参数。如果设置，uv 不会为给定空格分隔的包列表构建源分发版。

UV_NO_CACHE

等同于 --no-cache 命令行参数。如果设置，uv 将不会为任何操作使用缓存。

UV_NO_CONFIG

相当于 --no-config 命令行参数。如果设置，uv 将不会从当前目录、父目录或用户配置目录中读取任何配置文件。

UV_NO_ENV_FILE

在执行 uv run 命令时忽略 .env 文件。

UV_NO_INSTALLER_METADATA

跳过将 uv 安装器元数据文件（例如，INSTALLER、REQUESTED 和 direct_url.json）写入 .dist-info 目录的 site-packages 中。

UV_NO_MANAGED_PYTHON

禁用 uv-managed Python 版本的用法。

UV_NO_PROGRESS

等同于 --no-progress 命令行参数。禁用所有进度输出。例如，旋转器和进度条。

UV_NO_SYNC

等同于 --no-sync 命令行参数。如果设置，uv 将跳过更新环境。

UV_NO_VERIFY_HASHES

等同于 --no-verify-hashes 参数。禁用 requirements.txt 文件的哈希验证。

UV_NO_WRAP

用于禁用诊断的换行。

UV_OFFLINE

等效于 --offline 命令行参数。如果设置，uv 将禁用网络访问。

UV_OVERRIDE

等同于命令行参数 --override。如果设置，uv 将使用此文件作为覆盖文件。使用空格分隔的文件列表。

UV_PRERELEASE

等同于 --prerelease 命令行参数。例如，如果设置为 allow，uv 将允许所有依赖项使用预发布版本。

UV_PREVIEW

等同于 --preview 参数。启用预览模式。

UV_PROJECT_ENVIRONMENT

指定用于项目虚拟环境的目录路径。

有关更多详细信息，请参阅项目文档。

UV_PUBLISH_CHECK_URL

如果文件在索引中已存在，则不要上传文件。该值是索引的URL。

UV_PUBLISH_INDEX

相当于 uv publish 命令行中的 --index 参数。如果设置，则在发布配置中使用此名称的索引。

UV_PUBLISH_PASSWORD

等效于 uv publish 命令行中的 --password 参数。如果设置，uv 将使用此密码进行发布。

UV_PUBLISH_TOKEN

等同于 uv publish 命令行中的 --token 参数。如果设置，uv 将使用此令牌（用户名为 __token__）进行发布。

UV_PUBLISH_URL

相当于 --publish-url 命令行参数。使用 uv publish 时要使用的索引上传端点的 URL。

UV_PUBLISH_USERNAME

等同于 uv publish 命令行参数中的 --username。如果设置，uv 将使用此用户名进行发布。

UV_PYPY_INSTALL_MIRROR

管理 PyPy 安装是从 python.org 下载的。

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

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

UV_PYTHON_DOWNLOADS

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

UV_PYTHON_INSTALL_DIR

指定存储托管 Python 安装的目录。

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版本。

UV_REQUEST_TIMEOUT

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

UV_REQUIRE_HASHES

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

UV_RESOLUTION

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

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

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

JPY_SESSION_NAME

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

KSH_VERSION

用于检测 Ksh shell 的使用。

LOCALAPPDATA

用于查找 Microsoft Store Python 安装。

MACOSX_DEPLOYMENT_TARGET

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

默认为 12.0，即撰写时的最新非 EOL（过时）的 macOS 版本。

NETRC

用于设置 .netrc 文件位置。

NO_COLOR

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

查看 no-color.org。

NU_VERSION

用于检测 NuShell 使用情况。

PAGER

标准的 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 crate 兼容的任何过滤器。

例如：

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

有关更多信息，请参阅 跟踪文档。

RUST_MIN_STACK

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

值以字节为单位，默认通常是 2MB（2097152）。与正常的 RUST_MIN_STACK 语义不同，这可以影响主线程的堆栈大小，因为我们实际上会创建自己的 main2 线程来绕过 Windows 的真实主线程只有 1MB 的事实。该线程的大小为 max(RUST_MIN_STACK, 4MB)。

SHELL

标准 SHELL posix 环境变量。

SSL_CERT_FILE

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

SSL_CLIENT_CERT

如果设置，uv 将使用此文件进行 mTLS 认证。这应该是一个包含证书和私钥的 PEM 格式的单个文件。

SYSTEMDRIVE

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

TRACING_DURATIONS_FILE

用于通过 tracing-durations-export 功能创建跟踪持续时间文件。

USERPROFILE

Windows 系统上用户配置文件根目录的路径。

UV

用于调用 uv 的二进制文件的路径。

这将传播到由 uv 启动的所有子进程。

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

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

VIRTUAL_ENV

用于检测一个已激活的虚拟环境。

VIRTUAL_ENV_DISABLE_PROMPT

如果在一个虚拟环境激活之前设置为 1，则虚拟环境名称将不会添加到终端提示符之前。

XDG_BIN_HOME

可执行文件安装的目录路径。

XDG_CACHE_HOME

Unix 系统上缓存目录的路径。

XDG_CONFIG_DIRS

Unix 系统上系统级配置目录的路径。

XDG_CONFIG_HOME

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

XDG_DATA_HOME

存储管理的 Python 安装和工具的目录路径。

ZDOTDIR

用于确定当使用 Zsh 时使用哪个 .zshenv。

认证

Git 认证

uv 允许从 Git 安装软件包，并支持以下方案用于与私有仓库进行认证。

使用 SSH：

有关如何配置 SSH 的更多详细信息，请参阅 GitHub SSH 文档。

使用密码或令牌：

  • git+https://<user>:<token>@<hostname>/... (例如，git+https://git:[email protected]/astral-sh/uv)
  • git+https://<token>@<hostname>/... (例如，git+https://[email protected]/astral-sh/uv)
  • git+https://<user>@<hostname>/... (例如，git+https://[email protected]/astral-sh/uv)

当使用 GitHub 个人访问令牌时，用户名是任意的。GitHub 不支持直接使用密码登录，尽管其他主机可能支持。如果提供了没有凭证的用户名，您将被提示输入它们。

如果 URL 中没有凭证且需要进行认证，将查询 Git 凭证助手。

HTTP 认证

uv 在查询包注册表时支持通过 HTTP 传输凭据。

认证可以来自以下来源，按照优先级排序：

  • URL，例如，https://<用户>:<密码>@<主机>/...
  • .netrc 配置文件
  • 密钥圈 提供者（需要用户同意）

如果在单个 net 位置（方案、主机和端口）找到了认证，它将在命令期间进行缓存，并用于对该 net 位置的其他查询。认证不会在 uv 的调用之间进行缓存。

.netrc 认证默认启用，如果定义了 NETRC 环境变量，将尊重该变量，如果没有，则回退到 ~/.netrc。

要启用基于密钥圈的认证，将 --keyring-provider subprocess 命令行参数传递给 uv，或设置 UV_KEYRING_PROVIDER=subprocess。

可以在以下上下文中使用认证的主机：

  • [索引]
  • index-url
  • extra-index-url
  • find-links
  • package @ https://...

有关索引 URL 认证的详细信息，请参阅 索引认证文档。

有关与 pip 的差异的详细信息，请参阅 pip 兼容性指南。

使用替代包索引进行身份验证

请参阅替代索引集成指南以获取有关使用流行的替代Python包索引进行身份验证的详细信息。

自定义 CA 证书

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的一个可靠信任根集合，包括它们在 uv 中可以提高可移植性和性能（尤其是在 macOS 上，读取系统信任存储会带来显著的延迟）。

然而，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，对于强制性的代理），则可以设置 uv 使用系统信任存储，通过运行 uv 并带有 --native-tls 命令行标志，或将 UV_NATIVE_TLS 环境变量设置为 true。

如果需要直接路径到证书（例如，在 CI 中），将 SSL_CERT_FILE 环境变量设置为证书捆绑的路径，以指示 uv 使用该文件而不是系统的信任存储。

如果您希望进行客户端证书身份验证（mTLS），将 SSL_CLIENT_CERT 环境变量设置为包含证书的 PEM 格式文件的路径，后跟私钥。

最后，如果您正在使用一个您想要信任自签名证书或禁用证书验证的设置，可以通过 allow-insecure-host 配置选项指示 uv 允许到专用主机的非安全连接。例如，将以下内容添加到 pyproject.toml 将允许到 example.com 的非安全连接：

yaml 复制代码 
[tool.uv]
allow-insecure-host = ["example.com"]

allow-insecure-host 期望接收一个主机名（例如，localhost）或主机名-端口号对（例如，localhost:8080），并且仅适用于 HTTPS 连接，因为 HTTP 连接本身是不安全的。

使用 allow-insecure-host 时请谨慎，并且仅在受信任的环境中使用，因为它可能由于缺少证书验证而使您面临安全风险。

包索引

默认情况下，uv 使用 Python 包索引 (PyPI) 进行依赖解析和包安装。然而，uv 可以通过 [[tool.uv.index]] 配置选项（以及类似的命令行选项 --index）配置为使用其他包索引，包括私有索引。

定义索引

在解决依赖关系时包含一个额外的索引，请将 [[tool.uv.index]] 条目添加到您的 pyproject.toml 文件中：

yaml 复制代码 
[[tool.uv.index]]
# Optional name for the index.
name = "pytorch"

# Required URL for the index.
url = "https://download.pytorch.org/whl/cpu"

索引按照它们定义的顺序进行优先级排序，这意味着在配置文件中首先列出的索引是解决依赖时首先咨询的索引，通过命令行提供的索引优先于配置文件中的索引。

默认情况下，uv 包含 Python 包索引 (PyPI) 作为"默认"索引，即当在其他索引中找不到任何包时使用的索引。要从索引列表中排除 PyPI，请在另一个索引条目上设置 default = true（或使用 --default-index 命令行选项）：

yaml 复制代码 
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
default = true

默认索引始终被视为最低优先级，无论其在索引列表中的位置如何。

索引名称只能包含字母数字字符、破折号、下划线和点，并且必须是有效的ASCII字符。

当在命令行上提供索引（使用 --index 或 --default-index）或通过环境变量（UV_INDEX 或 UV_DEFAULT_INDEX）时，名称是可选的，但可以使用 <name>=<url> 语法包含，例如：

shell 复制代码 
# On the command line.
$ uv lock --index pytorch=https://download.pytorch.org/whl/cpu

# Via an environment variable.
$ UV_INDEX=pytorch=https://download.pytorch.org/whl/cpu uv lock

将包固定到特定索引

可以通过指定 tool.uv.sources 条目中的索引来将包固定到特定索引。例如，要确保 torch 总是从 pytorch 索引安装，请将以下内容添加到您的 pyproject.toml 文件中：

yaml 复制代码 
[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

同样，要根据平台从不同的索引中提取，您可以提供一个通过环境标记消歧的源列表：
pyproject.toml

yaml 复制代码 
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = [
  { index = "pytorch-cu118", marker = "sys_platform == 'darwin'"},
  { index = "pytorch-cu124", marker = "sys_platform != 'darwin'"},
]

[[tool.uv.index]]
name = "pytorch-cu118"
url = "https://download.pytorch.org/whl/cu118"

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"

索引可以被标记为 explicit = true 以防止从该索引安装软件包，除非明确将其固定到该索引。例如，要确保从 pytorch 索引安装 torch，但所有其他软件包都从 PyPI 安装，请将以下内容添加到您的 pyproject.toml 文件中：

yaml 复制代码 
[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

命名索引通过 tool.uv.sources 引用时必须在项目的 pyproject.toml 文件中定义；通过命令行、环境变量或用户级配置提供的索引将不会被识别。

如果索引同时被标记为 default = true 和 explicit = true，则它将被视为显式索引（即，只能通过 tool.uv.sources 使用），同时移除 PyPI 作为默认索引。

在多个索引中进行搜索

默认情况下，uv将在包含指定包的第一个索引处停止搜索，并将解析限制在那些第一个索引上存在的版本（first-index）。

例如，如果通过[[tool.uv.index]]指定了内部索引，uv的行为将是这样：如果该包存在于该内部索引中，它将始终 从该内部索引安装，而不是从PyPI安装。意图是防止"依赖混淆"攻击，攻击者会在PyPI上发布一个与内部包同名的不良包，从而导致不良包被安装而不是内部包。例如，参见2022年12月的torchtriton攻击。

用户可以通过--index-strategy命令行选项或UV_INDEX_STRATEGY环境变量选择替代索引行为，这些选项支持以下值：

  • first-index（默认）：在每个索引中搜索每个包，将候选版本限制在包含该包的第一个索引中。
  • unsafe-first-match：在每个索引中搜索每个包，但优先考虑第一个具有兼容版本的索引，即使在其他索引上有更新的版本。
  • unsafe-best-match：在每个索引中搜索每个包，并从候选版本组合集中选择最佳版本。

虽然unsafe-best-match与pip的行为最接近，但它将用户暴露于"依赖混淆"攻击的风险。

认证

大多数私有软件包索引要求进行认证才能访问软件包，通常通过用户名和密码（或访问令牌）进行。

提示：有关使用特定私有索引提供商进行认证的详细信息（例如来自AWS、Azure或GCP），请参阅备用索引指南。

直接提供凭证

凭证可以直接通过环境变量或嵌入到URL中提供。

例如，假设有一个名为 internal-proxy 的索引，它需要一个用户名（public）和密码（koala），在您的 pyproject.toml 中定义该索引（不包含凭证）：

toml 复制代码 
[tool.poetry.dependencies]
# ...
yaml 复制代码 
[[tool.uv.index]]
name = "internal-proxy"
url = "https://example.com/simple"

从那里，您可以设置 UV_INDEX_INTERNAL_PROXY_USERNAME 和 UV_INDEX_INTERNAL_PROXY_PASSWORD 环境变量，其中 INTERNAL_PROXY 是索引名称的大写版本，非字母数字字符被下划线替换：

shell 复制代码 
export UV_INDEX_INTERNAL_PROXY_USERNAME=public
export UV_INDEX_INTERNAL_PROXY_PASSWORD=koala

通过通过环境变量提供凭据，您可以避免在明文 pyproject.toml 文件中存储敏感信息。

或者，凭证可以直接嵌入到索引定义中：

yaml 复制代码 
[[tool.uv.index]]
name = "internal"
url = "https://public:[email protected]/simple"

为了安全起见，凭证从不存储在 uv.lock 文件中；因此，uv 必须在安装时能够访问经过身份验证的 URL。

使用凭证提供程序

除了直接提供凭证外，uv 支持从 netrc 和 keyring 发现凭证。有关设置特定凭证提供程序的详细信息，请参阅HTTP 认证文档。

默认情况下，uv 会在查询提供程序之前尝试未认证的请求。如果请求失败，uv 将搜索凭证。如果找到凭证，将尝试进行认证请求。

注意：如果设置了用户名，uv将在进行未认证的请求之前搜索凭证。

一些索引（例如，GitLab）会将未经身份验证的请求转发到公共索引，如PyPI------这意味着uv将不会搜索凭据。此行为可以通过使用authenticate设置按索引更改。例如，要始终搜索凭据：

yaml 复制代码 
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
authenticate = "always"

当 authenticate 设置为 always 时，uv 将会积极搜索凭证，如果找不到凭证则会报错。

禁用身份验证

为了防止凭证泄露，可以为索引禁用身份验证：

yaml 复制代码 
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
authenticate = "never"

当 authenticate 设置为 never 时，uv 将永远不会搜索给定索引的凭据，如果直接提供了凭据，则会报错。

--index-url 和 --extra-index-url

除了 [[tool.uv.index]] 配置选项之外，uv 支持与 pip 风格的 --index-url 和 --extra-index-url 命令行选项兼容，其中 --index-url 定义默认索引，而 --extra-index-url 定义附加索引。

这些选项可以与 [[tool.uv.index]] 配置选项一起使用，并遵循相同的优先级规则：

  • 默认索引始终被视为最低优先级，无论是通过传统的 --index-url 参数、推荐的 --default-index 参数，还是带有 default = true 的 [[tool.uv.index]] 条目定义。
  • 索引按定义顺序进行咨询，无论是通过传统的 --extra-index-url 参数、推荐的 --index 参数，还是 [[tool.uv.index]] 条目。

实际上，--index-url 和 --extra-index-url 可以被视为未命名的 [[tool.uv.index]] 条目，其中前者启用了 default = true。在这种情况下，--index-url 映射到 --default-index，而 --extra-index-url 映射到 --index。2024年12月19日

配置 uv 安装器

更改安装路径

默认情况下，uv 安装到 ~/.local/bin。如果设置了 XDG_BIN_HOME，则将使用它。同样，如果设置了 XDG_DATA_HOME，目标目录将被推断为 XDG_DATA_HOME/../bin。

要更改安装路径，请使用 UV_INSTALL_DIR：

macOS 和 Linux

shell 复制代码 
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/custom/path" sh

Windows

复制代码 
powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\Custom\Path";irm https://astral.sh/uv/install.ps1 | iex}

禁用 shell 修改

安装程序还可能更新您的 shell 配置文件，以确保 uv 二进制文件位于您的 PATH 中。要禁用此行为，请使用 INSTALLER_NO_MODIFY_PATH。例如：

shell 复制代码 
$ curl -LsSf https://astral.sh/uv/install.sh | env INSTALLER_NO_MODIFY_PATH=1.sh

如果使用 INSTALLER_NO_MODIFY_PATH 安装，后续操作，如 uv self update，将不会修改您的shell配置文件。

未管理的安装

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

shell 复制代码 
curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL="/custom/path".sh

UV_UNMANAGED_INSTALL 的使用也将禁用自动更新（通过 uv self update）。

将选项传递给安装脚本

建议使用环境变量，因为它们在各个平台上都是一致的。然而，也可以直接将选项传递给安装脚本。例如，要查看可用的选项：

shell 复制代码 
curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help

2025-03-24（一）

相关推荐
gywl3 小时前
【MySQL】索引 & 事务
数据库·mysql·事务·索引·隔离性
三金C_C9 小时前
docker使用uv安装依赖
docker·容器·uv
伊织code1 天前
uv - Guides 指南 [官方文档翻译]
python·脚本·pip·uv·依赖·guide
瞌睡不来2 天前
(学习总结30)Linux 进程优先级、进程切换和环境变量
linux·学习·进程·环境变量
辛普森Mmmm2 天前
黑马点评-UV统计
uv
互联网之声2 天前
盘泰UV种植体：抗老化新科技，焕发种植牙新活力
科技·uv
aiweker2 天前
使用 UV 管理 Python 项目 | python小知识
人工智能·python·uv
三金C_C2 天前
UV-Python包高效管理工具
python·uv
比花花解语3 天前
SQL中的索引是什么
数据库·sql·索引
热门推荐
01RAG 实践- Ollama+RagFlow 部署本地知识库02如何在WPS和Word/Excel中直接使用DeepSeek功能03DeepSeek各版本说明与优缺点分析04本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程05本地部署DeepSeek教程（Mac版本）06从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑07苍穹外卖面试总结08FreeCAD傻瓜教程之创建参数化几何图形-螺旋体、平面、球体、椭球体、圆柱体、圆锥体、棱柱、椭圆09DeepSeek R1本地化部署 Ollama + Chatbox 打造最强 AI 工具10LLaMA-Factory DeepSeek-R1 模型 微调基础教程