跳到内容

身份验证

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 中使用您的帐户名和密码，尽管其他主机可能会允许。

如果 URL 中没有凭据，并且需要身份验证，则将查询 Git 凭据助手。

重要

使用 uv add 时，uv _不会_将 Git 凭据持久化到 pyproject.toml 或 uv.lock。 这些文件通常包含在源代码管理和分发中，因此通常将凭据包含在其中是不安全的。

如果您已配置 Git 凭据助手，则您的凭据可能会自动持久化，从而成功后续获取依赖项。 但是，如果您没有 Git 凭据助手，或者项目在没有凭据种子的计算机上使用，则 uv 将无法获取依赖项。

您可以 _强制_ uv 通过将 --raw 选项传递给 uv add 来持久化 Git 凭据。 但是，我们强烈建议设置一个 凭据助手。

Git 凭据助手

Git 凭据助手用于存储和检索 Git 凭据。 请参阅 Git 文档以了解更多信息。

如果您正在使用 GitHub，设置凭据助手最简单的方法是安装 gh CLI 并使用

$ gh auth login

有关更多详细信息，请参阅 gh auth login 文档。

注意

以交互方式使用 gh auth login 时，将自动配置凭据助手。 但是，当使用 gh auth login --with-token 时，如 uv GitHub Actions 指南中所示，需要运行 gh auth setup-git 命令才能配置凭据助手。

HTTP 身份验证

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

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

  • URL，例如 https://<user>:<password>@<hostname>/...
  • .netrc 配置文件
  • keyring 提供程序（需要选择加入）

如果为单个索引 URL 或网络位置（方案、主机和端口）找到身份验证，它将被缓存以供命令持续时间使用，并用于对该索引或网络位置的其他查询。 身份验证不会在 uv 的调用之间缓存。

默认情况下启用 .netrc 身份验证，如果已定义，将遵守 NETRC 环境变量，如果未定义，则回退到 ~/.netrc。

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

身份验证可用于在以下上下文中指定的主机

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

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

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

重要

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

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

使用其他软件包索引进行身份验证

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

自定义 CA 证书

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

但是，在某些情况下，您可能希望使用平台的本机证书存储，特别是如果您依赖于公司信任根（例如，对于强制代理），该信任根包含在系统的证书存储中。 要指示 uv 使用系统的信任存储，请使用 --native-tls 命令行标志运行 uv，或将 UV_NATIVE_TLS 环境变量设置为 true。

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

如果需要客户端证书身份验证 (mTLS)，请将 SSL_CLIENT_CERT 环境变量设置为 PEM 格式文件的路径，该文件包含证书和私钥。

最后，如果您使用的设置需要信任自签名证书或以其他方式禁用证书验证，则可以指示 uv 通过 allow-insecure-host 配置选项允许与专用主机建立不安全连接。 例如，将以下内容添加到 pyproject.toml 将允许与 example.com 建立不安全连接

[tool.uv]
allow-insecure-host = ["example.com"]

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

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