Document HTTP authentication (#2425)

PIP_COMPATIBILITY.md

@@ -312,6 +312,15 @@ If you encounter a missing option or subcommand, please search the issue tracker
 already been reported, and if not, consider opening a new issue. Feel free to upvote any existing
 issues to convey your interest.
 
+## Registry authentication
+
+uv does not support `pip`'s `auto` or `import` options for `--keyring-provider` — only `subproces` is supported.
+
+Unlike `pip`, uv does not enable keyring authentication by default.
+
+Unlike `pip`, uv does not wait until a request returns a HTTP 401 before searching for authentication. uv attaches
+authentication to all requests for hosts with credentials available.
+
 ## Legacy features
 
 `uv` does not support features that are considered legacy or deprecated in `pip`. For example,

README.md

@@ -206,6 +206,33 @@ When using a GitHub personal access token, the username is arbitrary. GitHub doe
 
 If there are no credentials present in the URL and authentication is needed, the [Git credential helper](https://git-scm.com/doc/credential-helpers) will be queried.
 
+### 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://<user>:<password>@<hostname>/...`
+- 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 net location (scheme, host, and port), it will be cached for the duration
+of the command and used for other queries to that net location. Authentication is not cached across invocations of
+uv.
+
+Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable keyring-based
+authentication.
+
+Authentication may be used for hosts specified in the following contexts:
+
+- `index-url`
+- `extra-index-url`
+- `find-links`
+- `package @ https://...`
+
+See the [`pip` compatibility guide](PIP_COMPATIBILITY.md#registry-authentication) for details on differences from
+`pip`.
+
 ### Dependency caching
 
 uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have