3.14.2 HTTP 身份验证

原文链接: https://docs.astral.sh/uv/concepts/authentication/http/

3.14.2 HTTP 身份验证

查询包仓库时，uv 支持通过 HTTP 提供凭据。

身份验证可以来自以下来源，按优先级排序：

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

身份验证可以用于以下场景中指定的主机：

• [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。目前该文件不打算供手动编辑。

注意

安全的系统原生存储机制处于预览阶段 —— 它仍是实验性的，正在积极开发中。未来它将成为默认的存储机制。

启用后，uv 会使用你操作系统原生的密钥存储机制。在 macOS 上使用 Keychain Services；在 Windows 上使用 Windows 凭据管理器；在 Linux 上使用基于 DBus 的 Secret Service API。

目前 uv 只会在原生存储中查找它自己添加的凭据 —— 它不会检索其他应用持久化的凭据。

设置 UV_PREVIEW_FEATURES=native-auth 即可使用该存储机制。

keyring 提供程序

keyring 提供程序是来自 pip 的概念，允许通过与流行的 keyring Python 包一致的接口获取凭据。

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

设置 --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 兼容性指南。