mirror of https://github.com/astral-sh/uv
Split the "Authentication" page into sections (#15575)
In preparation for more content for #15570
This commit is contained in:
Zanie Blue
GitHub
parent
f461438611
commit
bf189c5414
|
|
@ -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@<hostname>/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`)
|
||||
- `git+ssh://git@<host>/...` (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://<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`)
|
||||
|
||||
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://<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 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/<user>/<name>/resolve/<branch>/main.py
|
||||
```
|
||||
|
||||
You can disable automatic Hugging Face authentication by setting the `UV_NO_HF_TOKEN=1` environment
|
||||
variable.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.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://<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.
|
||||
|
|
@ -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`.
|
||||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`:
|
||||
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue