From bf189c54142b9ab7a5fc1157f18c8b72d2d67c4d Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Thu, 28 Aug 2025 15:45:31 -0500 Subject: [PATCH] Split the "Authentication" page into sections (#15575) In preparation for more content for #15570 --- docs/concepts/authentication.md | 168 ------------------- docs/concepts/authentication/certificates.md | 41 +++++ docs/concepts/authentication/git.md | 70 ++++++++ docs/concepts/authentication/http.md | 48 ++++++ docs/concepts/authentication/index.md | 10 ++ docs/concepts/authentication/third-party.md | 21 +++ docs/concepts/index.md | 2 +- docs/concepts/indexes.md | 4 +- docs/guides/integration/github.md | 4 +- docs/js/extra.js | 16 ++ docs/pip/packages.md | 4 +- mkdocs.template.yml | 11 +- 12 files changed, 221 insertions(+), 178 deletions(-) delete mode 100644 docs/concepts/authentication.md create mode 100644 docs/concepts/authentication/certificates.md create mode 100644 docs/concepts/authentication/git.md create mode 100644 docs/concepts/authentication/http.md create mode 100644 docs/concepts/authentication/index.md create mode 100644 docs/concepts/authentication/third-party.md diff --git a/docs/concepts/authentication.md b/docs/concepts/authentication.md deleted file mode 100644 index fe5314b85..000000000 --- a/docs/concepts/authentication.md +++ /dev/null @@ -1,168 +0,0 @@ -# Authentication - -## Git authentication - -uv allows packages to be installed from Git and supports the following schemes for authenticating -with private repositories. - -Using SSH: - -- `git+ssh://git@/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`) -- `git+ssh://git@/...` (e.g., `git+ssh://git@github.com-key-2/astral-sh/uv`) - -See the -[GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) -for more details on how to configure SSH. - -Using a password or token: - -- `git+https://:@/...` (e.g., - `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) -- `git+https://@/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`) -- `git+https://@/...` (e.g., `git+https://git@github.com/astral-sh/uv`) - -When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to -use your account name and password in URLs like this, although other hosts may. - -If there are no credentials present in the URL and authentication is needed, the -[Git credential helper](#git-credential-helpers) will be queried. - -!!! important - - When using `uv add`, uv _will not_ persist Git credentials to the `pyproject.toml` or `uv.lock`. - These files are often included in source control and distributions, so it is generally unsafe - to include credentials in them. - - If you have a Git credential helper configured, your credentials may be automatically persisted, - resulting in successful subsequent fetches of the dependency. However, if you do not have a Git - credential helper or the project is used on a machine without credentials seeded, uv will fail to - fetch the dependency. - - You _may_ force uv to persist Git credentials by passing the `--raw` option to `uv add`. However, - we strongly recommend setting up a [credential helper](#git-credential-helpers) instead. - -### Git credential helpers - -Git credential helpers are used to store and retrieve Git credentials. See the -[Git documentation](https://git-scm.com/doc/credential-helpers) to learn more. - -If you're using GitHub, the simplest way to set up a credential helper is to -[install the `gh` CLI](https://github.com/cli/cli#installation) and use: - -```console -$ gh auth login -``` - -See the [`gh auth login`](https://cli.github.com/manual/gh_auth_login) documentation for more -details. - -!!! note - - When using `gh auth login` interactively, the credential helper will be configured automatically. - But when using `gh auth login --with-token`, as in the uv - [GitHub Actions guide](../guides/integration/github.md#private-repos), the - [`gh auth setup-git`](https://cli.github.com/manual/gh_auth_setup-git) command will need to be - run afterwards to configure the credential helper. - -## HTTP authentication - -uv supports credentials over HTTP when querying package registries. - -Authentication can come from the following sources, in order of precedence: - -- The URL, e.g., `https://:@/...` -- A [`.netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file -- A [keyring](https://github.com/jaraco/keyring) provider (requires opt-in) - -If authentication is found for a single index URL or net location (scheme, host, and port), it will -be cached for the duration of the command and used for other queries to that index or net location. -Authentication is not cached across invocations of uv. - -`.netrc` authentication is enabled by default, and will respect the `NETRC` environment variable if -defined, falling back to `~/.netrc` if not. - -To enable keyring-based authentication, pass the `--keyring-provider subprocess` command-line -argument to uv, or set `UV_KEYRING_PROVIDER=subprocess`. - -Authentication may be used for hosts specified in the following contexts: - -- `[index]` -- `index-url` -- `extra-index-url` -- `find-links` -- `package @ https://...` - -See the [index authentication documentation](./indexes.md#authentication) for details on -authenticating index URLs. - -See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on -differences from `pip`. - -!!! important - - When using `uv add`, uv _will not_ persist index credentials to the `pyproject.toml` or `uv.lock`. - These files are often included in source control and distributions, so it is generally unsafe - to include credentials in them. However, uv _will_ persist credentials for direct URLs, i.e., - `package @ https://username:password:example.com/foo.whl`, as there is not currently a way to - otherwise provide those credentials. - - If credentials were attached to an index URL during `uv add`, uv may fail to fetch dependencies - from indexes which require authentication on subsequent operations. See the - [index authentication documentation](./indexes.md#authentication) for details on persistent - authentication for indexes. - -## Authentication with alternative package indexes - -See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for -details on authentication with popular alternative Python package indexes. - -## Custom CA certificates - -By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a -reliable set of trust roots from Mozilla, and including them in uv improves portability and -performance (especially on macOS, where reading the system trust store incurs a significant delay). - -However, in some cases, you may want to use the platform's native certificate store, especially if -you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your -system's certificate store. To instruct uv to use the system's trust store, run uv with the -`--native-tls` command-line flag, or set the `UV_NATIVE_TLS` environment variable to `true`. - -If a direct path to the certificate is required (e.g., in CI), set the `SSL_CERT_FILE` environment -variable to the path of the certificate bundle, to instruct uv to use that file instead of the -system's trust store. - -If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment -variable to the path of the PEM formatted file containing the certificate followed by the private -key. - -Finally, if you're using a setup in which you want to trust a self-signed certificate or otherwise -disable certificate verification, you can instruct uv to allow insecure connections to dedicated -hosts via the `allow-insecure-host` configuration option. For example, adding the following to -`pyproject.toml` will allow insecure connections to `example.com`: - -```toml -[tool.uv] -allow-insecure-host = ["example.com"] -``` - -`allow-insecure-host` expects to receive a hostname (e.g., `localhost`) or hostname-port pair (e.g., -`localhost:8080`), and is only applicable to HTTPS connections, as HTTP connections are inherently -insecure. - -Use `allow-insecure-host` with caution and only in trusted environments, as it can expose you to -security risks due to the lack of certificate verification. - -## Hugging Face support - -uv supports automatic authentication for the Hugging Face Hub. Specifically, if the `HF_TOKEN` -environment variable is set, uv will propagate it to requests to `huggingface.co`. - -This is particularly useful for accessing private scripts in Hugging Face Datasets. For example, you -can run the following command to execute the script `main.py` script from a private dataset: - -```console -$ HF_TOKEN=hf_... uv run https://huggingface.co/datasets///resolve//main.py -``` - -You can disable automatic Hugging Face authentication by setting the `UV_NO_HF_TOKEN=1` environment -variable. diff --git a/docs/concepts/authentication/certificates.md b/docs/concepts/authentication/certificates.md new file mode 100644 index 000000000..648e38d9b --- /dev/null +++ b/docs/concepts/authentication/certificates.md @@ -0,0 +1,41 @@ +# TLS certificates + +By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a +reliable set of trust roots from Mozilla, and including them in uv improves portability and +performance (especially on macOS, where reading the system trust store incurs a significant delay). + +## System certificates + +In some cases, you may want to use the platform's native certificate store, especially if you're +relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's +certificate store. To instruct uv to use the system's trust store, run uv with the `--native-tls` +command-line flag, or set the `UV_NATIVE_TLS` environment variable to `true`. + +## Custom certificates + +If a direct path to the certificate is required (e.g., in CI), set the `SSL_CERT_FILE` environment +variable to the path of the certificate bundle, to instruct uv to use that file instead of the +system's trust store. + +If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment +variable to the path of the PEM formatted file containing the certificate followed by the private +key. + +## Insecure hosts + +If you're using a setup in which you want to trust a self-signed certificate or otherwise disable +certificate verification, you can instruct uv to allow insecure connections to dedicated hosts via +the `allow-insecure-host` configuration option. For example, adding the following to +`pyproject.toml` will allow insecure connections to `example.com`: + +```toml +[tool.uv] +allow-insecure-host = ["example.com"] +``` + +`allow-insecure-host` expects to receive a hostname (e.g., `localhost`) or hostname-port pair (e.g., +`localhost:8080`), and is only applicable to HTTPS connections, as HTTP connections are inherently +insecure. + +Use `allow-insecure-host` with caution and only in trusted environments, as it can expose you to +security risks due to the lack of certificate verification. diff --git a/docs/concepts/authentication/git.md b/docs/concepts/authentication/git.md new file mode 100644 index 000000000..f07aed01c --- /dev/null +++ b/docs/concepts/authentication/git.md @@ -0,0 +1,70 @@ +# Git credentials + +uv allows packages to be installed from private Git repositories using SSH or HTTP authentication. + +## SSH authentication + +To authenticate using an SSH key, use the `ssh://` protocol: + +- `git+ssh://git@/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`) +- `git+ssh://git@/...` (e.g., `git+ssh://git@github.com-key-2/astral-sh/uv`) + +SSH authentication requires using the username `git`. + +See the +[GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) +for more details on how to configure SSH. + +### HTTP authentication + +To authenticate over HTTP Basic authentication using a password or token: + +- `git+https://:@/...` (e.g., + `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) +- `git+https://@/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`) +- `git+https://@/...` (e.g., `git+https://git@github.com/astral-sh/uv`) + +!!! note + + When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to + use your account name and password in URLs like this, although other hosts may. + +If there are no credentials present in the URL and authentication is needed, the +[Git credential helper](#git-credential-helpers) will be queried. + +## Persistence of credentials + +When using `uv add`, uv _will not_ persist Git credentials to the `pyproject.toml` or `uv.lock`. +These files are often included in source control and distributions, so it is generally unsafe to +include credentials in them. + +If you have a Git credential helper configured, your credentials may be automatically persisted, +resulting in successful subsequent fetches of the dependency. However, if you do not have a Git +credential helper or the project is used on a machine without credentials seeded, uv will fail to +fetch the dependency. + +You _may_ force uv to persist Git credentials by passing the `--raw` option to `uv add`. However, we +strongly recommend setting up a [credential helper](#git-credential-helpers) instead. + +## Git credential helpers + +Git credential helpers are used to store and retrieve Git credentials. See the +[Git documentation](https://git-scm.com/doc/credential-helpers) to learn more. + +If you're using GitHub, the simplest way to set up a credential helper is to +[install the `gh` CLI](https://github.com/cli/cli#installation) and use: + +```console +$ gh auth login +``` + +See the [`gh auth login`](https://cli.github.com/manual/gh_auth_login) documentation for more +details. + +!!! note + + When using `gh auth login` interactively, the credential helper will be configured automatically. + But when using `gh auth login --with-token`, as in the uv + [GitHub Actions guide](../../guides/integration/github.md#private-repos), the + [`gh auth setup-git`](https://cli.github.com/manual/gh_auth_setup-git) command will need to be + run afterwards to configure the credential helper. diff --git a/docs/concepts/authentication/http.md b/docs/concepts/authentication/http.md new file mode 100644 index 000000000..02dee6b1e --- /dev/null +++ b/docs/concepts/authentication/http.md @@ -0,0 +1,48 @@ +# HTTP credentials + +uv supports credentials over HTTP when querying package registries. + +Authentication can come from the following sources, in order of precedence: + +- The URL, e.g., `https://:@/...` +- A [`.netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file +- A [keyring](https://github.com/jaraco/keyring) provider (requires opt-in) + +`.netrc` authentication is enabled by default, and will respect the `NETRC` environment variable if +defined, falling back to `~/.netrc` if not. + +To enable keyring-based authentication, pass the `--keyring-provider subprocess` command-line +argument to uv, or set `UV_KEYRING_PROVIDER=subprocess`. + +Authentication may be used for hosts specified in the following contexts: + +- `[index]` +- `index-url` +- `extra-index-url` +- `find-links` +- `package @ https://...` + +## Persistence of credentials + +If authentication is found for a single index URL or net location (scheme, host, and port), it will +be cached for the duration of the command and used for other queries to that index or net location. +Authentication is not cached across invocations of uv. + +When using `uv add`, uv _will not_ persist index credentials to the `pyproject.toml` or `uv.lock`. +These files are often included in source control and distributions, so it is generally unsafe to +include credentials in them. However, uv _will_ persist credentials for direct URLs, i.e., +`package @ https://username:password:example.com/foo.whl`, as there is not currently a way to +otherwise provide those credentials. + +If credentials were attached to an index URL during `uv add`, uv may fail to fetch dependencies from +indexes which require authentication on subsequent operations. See the +[index authentication documentation](../indexes.md#authentication) for details on persistent +authentication for indexes. + +## Learn more + +See the [index authentication documentation](../indexes.md#authentication) for details on +authenticating index URLs. + +See the [`pip` compatibility guide](../../pip/compatibility.md#registry-authentication) for details +on differences from `pip`. diff --git a/docs/concepts/authentication/index.md b/docs/concepts/authentication/index.md new file mode 100644 index 000000000..ff0ce4d8c --- /dev/null +++ b/docs/concepts/authentication/index.md @@ -0,0 +1,10 @@ +# Authentication + +Authentication is required when working with private repositories or package indexes. + +Learn more about authentication in uv: + +- [HTTP authentication](./http.md) +- [Git authentication](./git.md) +- [TLS certificates](./certificates.md) +- [Third-party services](./third-party.md) diff --git a/docs/concepts/authentication/third-party.md b/docs/concepts/authentication/third-party.md new file mode 100644 index 000000000..de9cb2fef --- /dev/null +++ b/docs/concepts/authentication/third-party.md @@ -0,0 +1,21 @@ +# Third-party services + +## Authentication with alternative package indexes + +See the [alternative indexes integration guide](../../guides/integration/alternative-indexes.md) for +details on authentication with popular alternative Python package indexes. + +## Hugging Face support + +uv supports automatic authentication for the Hugging Face Hub. Specifically, if the `HF_TOKEN` +environment variable is set, uv will propagate it to requests to `huggingface.co`. + +This is particularly useful for accessing private scripts in Hugging Face Datasets. For example, you +can run the following command to execute the script `main.py` script from a private dataset: + +```console +$ HF_TOKEN=hf_... uv run https://huggingface.co/datasets///resolve//main.py +``` + +You can disable automatic Hugging Face authentication by setting the `UV_NO_HF_TOKEN=1` environment +variable. diff --git a/docs/concepts/index.md b/docs/concepts/index.md index f9249bd31..ac88e01fb 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -9,7 +9,7 @@ Read the concept documents to learn more about uv's features: - [Package indexes](./indexes.md) - [Resolution](./resolution.md) - [The uv build backend](./build-backend.md) -- [Authentication](./authentication.md) +- [Authentication](./authentication/index.md) - [Caching](./cache.md) - [The pip interface](../pip/index.md) diff --git a/docs/concepts/indexes.md b/docs/concepts/indexes.md index 5e6c3866c..7dca6ea14 100644 --- a/docs/concepts/indexes.md +++ b/docs/concepts/indexes.md @@ -184,8 +184,8 @@ access to the authenticated URL at installation time. ### Using credential providers In addition to providing credentials directly, uv supports discovery of credentials from netrc and -keyring. See the [HTTP authentication](./authentication.md#http-authentication) documentation for -details on setting up specific credential providers. +keyring. See the [HTTP authentication](./authentication/http.md) documentation for details on +setting up specific credential providers. By default, uv will attempt an unauthenticated request before querying providers. If the request fails, uv will search for credentials. If credentials are found, an authenticated request will be diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md index b8d411b24..a866f562c 100644 --- a/docs/guides/integration/github.md +++ b/docs/guides/integration/github.md @@ -325,8 +325,8 @@ secret]. Then, you can use the [`gh`](https://cli.github.com/) CLI (which is installed in GitHub Actions runners by default) to configure a -[credential helper for Git](../../concepts/authentication.md#git-credential-helpers) to use the PAT -for queries to repositories hosted on `github.com`. +[credential helper for Git](../../concepts/authentication/git.md#git-credential-helpers) to use the +PAT for queries to repositories hosted on `github.com`. For example, if you called your repository secret `MY_PAT`: diff --git a/docs/js/extra.js b/docs/js/extra.js index d059d2875..818be7724 100644 --- a/docs/js/extra.js +++ b/docs/js/extra.js @@ -88,6 +88,22 @@ document$.subscribe(function () { "concepts/projects/run/#legacy-scripts-on-windows", "concepts/projects/sync/#checking-if-the-lockfile-is-up-to-date": "concepts/projects/sync/#checking-the-lockfile", + "concepts/authentication/#git-authentication": + "concepts/authentication/git/", + "concepts/authentication/#git-credential-helpers": + "concepts/authentication/git/#git-credential-helpers", + "concepts/authentication/#http-authentication": + "concepts/authentication/http/", + "concepts/authentication/#using-netrc-files": + "concepts/authentication/http/#using-netrc-files", + "concepts/authentication/#using-the-keyring": + "concepts/authentication/http/#using-the-keyring", + "concepts/authentication/#authentication-with-alternative-package-indexes": + "concepts/authentication/http/#authentication-with-alternative-package-indexes", + "concepts/authentication/#custom-ca-certificates": + "concepts/authentication/certificates/", + "concepts/authentication/#hugging-face-support": + "concepts/authentication/third-party/#hugging-face-support", }; // The prefix for the site, see `site_dir` in `mkdocs.yml` diff --git a/docs/pip/packages.md b/docs/pip/packages.md index cdce527b6..f14f21f5e 100644 --- a/docs/pip/packages.md +++ b/docs/pip/packages.md @@ -57,8 +57,8 @@ $ # Install a branch $ uv pip install "git+https://github.com/astral-sh/ruff@main" ``` -See the [Git authentication](../concepts/authentication.md#git-authentication) documentation for -installation from a private repository. +See the [Git authentication](../concepts/authentication/git.md) documentation for installation from +a private repository. ## Editable packages diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 342909bcf..537a1f23b 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -77,7 +77,7 @@ plugins: "reference/build_failures.md": "reference/troubleshooting/build-failures.md" "reference/resolver-internals.md": "reference/internals/resolver.md" "configuration/installer.md": "reference/installer.md" - "configuration/authentication.md": "concepts/authentication.md" + "configuration/authentication.md": "concepts/authentication/index.md" "configuration/build-backend.md": "concepts/build-backend.md" "configuration/files.md": "concepts/configuration-files.md" "configuration/indexes.md": "concepts/indexes.md" @@ -130,7 +130,7 @@ plugins: - concepts/indexes.md - concepts/resolution.md - concepts/build-backend.md - - concepts/authentication.md + - concepts/authentication/index.md - concepts/cache.md - concepts/preview.md The pip interface: @@ -210,7 +210,12 @@ nav: - Package indexes: concepts/indexes.md - Resolution: concepts/resolution.md - Build backend: concepts/build-backend.md - - Authentication: concepts/authentication.md + - Authentication: + - concepts/authentication/index.md + - HTTP credentials: concepts/authentication/http.md + - Git credentials: concepts/authentication/git.md + - TLS certificates: concepts/authentication/certificates.md + - Third-party services: concepts/authentication/third-party.md - Caching: concepts/cache.md - Preview features: concepts/preview.md # Note: The `pip` section was moved to the `concepts/` section but the