Split the "Authentication" page into sections (#15575)

zanieb · web-flow · commit bf189c54142b · 2025-08-28T15:45:31.000-05:00
In preparation for more content for #15570
diff --git a/docs/concepts/authentication.md b/docs/concepts/authentication.md
diff --git a/docs/concepts/authentication/certificates.md 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
@@ -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@<hostname>/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`)
+- `git+ssh://git@<host>/...` (e.g., `git+ssh://git@github.1485827954.workers.dev-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://<user>:<token>@<hostname>/...` (e.g.,
+  `git+https://git:github_pat_asdf@github.com/astral-sh/uv`)
+- `git+https://<token>@<hostname>/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`)
+- `git+https://<user>@<hostname>/...` (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
@@ -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://<user>:<password>@<hostname>/...`
+- 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
@@ -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
@@ -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/<user>/<name>/resolve/<branch>/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
@@ -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
@@ -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
@@ -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
diff --git a/docs/pip/packages.md b/docs/pip/packages.md
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
