Zanie Blue
92 lines
3.6 KiB
Markdown
92 lines
3.6 KiB
Markdown
# 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](#netrc-files) configuration file
|
|
- The uv credentials file
|
|
- A [keyring provider](#keyring-providers) (off by default)
|
|
|
|
Authentication may be used for hosts specified in the following contexts:
|
|
|
|
- `[index]`
|
|
- `index-url`
|
|
- `extra-index-url`
|
|
- `find-links`
|
|
- `package @ https://...`
|
|
|
|
## netrc files
|
|
|
|
[`.netrc`](https://everything.curl.dev/usingcurl/netrc) files are a long-standing plain text format
|
|
for storing credentials on a system.
|
|
|
|
Reading credentials from `.netrc` files is always enabled. The target file path will be loaded from
|
|
the `NETRC` environment variable if defined, falling back to `~/.netrc` if not.
|
|
|
|
## The uv credentials file
|
|
|
|
uv will read credentials from `~/.local/share/uv/credentials/credentials.toml`. This file is
|
|
currently not intended to be edited manually.
|
|
|
|
To add or remove credentials, use the [`uv auth` commands](./cli.md).
|
|
|
|
## Keyring providers
|
|
|
|
A keyring provider typically fetches credentials from an operating system store.
|
|
|
|
The keyring providers are not used by default.
|
|
|
|
### The 'subprocess' keyring provider
|
|
|
|
The 'subprocess' keyring provider invokes the `keyring` command to fetch credentials.
|
|
|
|
The expected interface for this is based on the popular [keyring](https://github.com/jaraco/keyring)
|
|
Python package. Similar support is built-in to pip.
|
|
|
|
Set `--keyring-provider subprocess`, `UV_KEYRING_PROVIDER=subprocess`, or
|
|
`tool.uv.keyring-provider = "subprocess"` to use the provider.
|
|
|
|
### The 'native' keyring provider
|
|
|
|
!!! note
|
|
|
|
The native keyring provider is in [preview](../preview.md) — it is still experimental and being
|
|
actively developed.
|
|
|
|
The native keyring provider uses the secret storage mechanism native to your operating system. On
|
|
macOS, it uses the Keychain Services. On Windows, it uses the Windows Credential Manager. On Linux,
|
|
it uses the DBus-based Secret Service API.
|
|
|
|
Currently, uv only searches the native keyring provider for credentials it has added to the secret
|
|
store. To add or remove credentials, use the [`uv auth` commands](./cli.md).
|
|
|
|
Set `--keyring-provider native`, `UV_KEYRING_PROVIDER=native`, or
|
|
`tool.uv.keyring-provider = "native"` to use the provider.
|
|
|
|
## 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`.
|