HTTP 凭据

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

认证信息可以来自以下来源，优先级由高到低排列：

• URL，例如 https://<user>:<password>@<hostname>/...
• netrc 配置文件
• uv 凭据存储
• 密钥环提供程序（默认关闭）

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

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

netrc 文件

.netrc 文件是一种长期存在的纯文本格式，用于在系统上存储凭据。

读取 .netrc 文件的功能始终处于启用状态。如果定义了 NETRC 环境变量，则从该变量指定的目标文件路径加载；否则回退到 ~/.netrc。

uv 凭据存储

uv 可以通过 uv auth 命令从存储中读取和写入凭据。

凭据以纯文本格式存储在 uv 的状态目录中，例如在 Unix 系统上位于 ~/.local/share/uv/credentials/credentials.toml。目前此文件不建议手动编辑。

注意

一种安全的、系统原生的存储机制目前处于 预览（preview）阶段——它仍处于实验性阶段且正在积极开发中。未来，这将成为默认的存储机制。

启用后，uv 将使用您操作系统原生的机密存储机制。在 macOS 上，它使用 Keychain Services；在 Windows 上，它使用 Windows 凭据管理器（Credential Manager）；在 Linux 上，它使用基于 DBus 的 Secret Service API。

目前，uv 仅在原生存储中搜索它自己添加的凭据——它不会检索由其他应用程序存储的凭据。

设置 UV_PREVIEW_FEATURES=native-auth 以使用此存储机制。

密钥环（Keyring）提供程序

密钥环提供程序是一个源自 pip 的概念，允许从符合流行的 keyring Python 包接口的地方检索凭据。

“subprocess”密钥环提供程序通过调用 keyring 命令来获取凭据。uv 目前不支持其他类型的密钥环提供程序。

设置 --keyring-provider subprocess、UV_KEYRING_PROVIDER=subprocess 或 tool.uv.keyring-provider = "subprocess" 以使用该提供程序。

凭据持久化

如果为某个索引 URL 或网络位置（方案、主机和端口）找到了认证信息，它将在命令运行期间被缓存，并用于该索引或网络位置的其他查询。认证信息不会跨 uv 的多次调用进行持久化缓存。

使用 uv add 时，uv 不会将索引凭据持久化到 pyproject.toml 或 uv.lock 中。这些文件通常会包含在源代码管理和分发包中，因此在其中包含凭据通常是不安全的。但是，uv 会为直接 URL（例如 package @ https://username:password:example.com/foo.whl）持久化凭据，因为目前没有其他方式提供这些凭据。

如果在 uv add 期间将凭据附加到索引 URL，uv 在后续操作中可能无法从需要认证的索引中获取依赖项。有关索引持久化认证的详细信息，请参阅索引认证文档。

了解更多

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

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