mirror of
https://github.com/astral-sh/uv.git
synced 2025-08-26 13:34:14 +00:00
d86075fc1e
## Summary This PR revives https://github.com/astral-sh/uv/pull/4944, which I think was a good start towards adding `--trusted-host`. Last night, I tried to add `--trusted-host` with a custom verifier, but we had to vendor a lot of `reqwest` code and I eventually hit some private APIs. I'm not confident that I can implement it correctly with that mechanism, and since this is security, correctness is the priority. So, instead, we now use two clients and multiplex between them. Closes https://github.com/astral-sh/uv/issues/1339. ## Test Plan Created self-signed certificate, and ran `python3 -m http.server --bind 127.0.0.1 4443 --directory . --certfile cert.pem --keyfile key.pem` from the packse index directory. Verified that `cargo run pip install transitive-yanked-and-unyanked-dependency-a-0abad3b6 --index-url https://127.0.0.1:8443/simple-html` failed with: ``` error: Request failed after 3 retries Caused by: error sending request for url (https://127.0.0.1:8443/simple-html/transitive-yanked-and-unyanked-dependency-a-0abad3b6/) Caused by: client error (Connect) Caused by: invalid peer certificate: Other(OtherError(CaUsedAsEndEntity)) ``` Verified that `cargo run pip install transitive-yanked-and-unyanked-dependency-a-0abad3b6 --index-url 'https://127.0.0.1:8443/simple-html' --trusted-host '127.0.0.1:8443'` failed with the expected error (invalid resolution) and made valid requests. Verified that `cargo run pip install transitive-yanked-and-unyanked-dependency-a-0abad3b6 --index-url 'https://127.0.0.1:8443/simple-html' --trusted-host '127.0.0.2' -n` also failed.
97 lines
4.3 KiB
Markdown
97 lines
4.3 KiB
Markdown
# 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 does not support
|
|
logging in with password directly, although other hosts may. If a username is provided without
|
|
credentials, you will be prompted to enter them.
|
|
|
|
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`.
|
|
|
|
## 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.
|
|
|
|
## 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.
|