pioduino/uv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Split the alternative indexes page into separate pages (#18607)

Browse Source 
Same idea as #18597
This commit is contained in:
Zanie Blue
2026-03-23 14:41:51 -05:00
committed by GitHub
parent 8a712b0b1a
commit 10477cd1ce
9 changed files with 456 additions and 442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/concepts/authentication/third-party.md
+6 -2
View File
@@ -2,8 +2,12 @@
## 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.
See the dedicated guides for authentication with popular alternative Python package indexes:
- [Azure Artifacts](../../guides/integration/azure.md)
- [Google Artifact Registry](../../guides/integration/google.md)
- [AWS CodeArtifact](../../guides/integration/aws.md)
- [JFrog Artifactory](../../guides/integration/jfrog.md)
## Hugging Face support
docs/concepts/indexes.md
+5 -2
View File
@@ -142,8 +142,11 @@ password (or access token).
!!! tip
See the [alternative index guide](../guides/integration/alternative-indexes.md) for details on
authenticating with specific private index providers, e.g., from AWS, Azure, or GCP.
See the dedicated guides for authenticating with specific private index providers:
[Azure Artifacts](../guides/integration/azure.md),
[Google Artifact Registry](../guides/integration/google.md),
[AWS CodeArtifact](../guides/integration/aws.md), and
[JFrog Artifactory](../guides/integration/jfrog.md).
### Providing credentials directly
docs/guides/integration/alternative-indexes.md
-435
View File
@@ -1,435 +0,0 @@
---
title: Using alternative package indexes
description:
A guide to using alternative package indexes with uv, including Azure Artifacts, Google Artifact
Registry, AWS CodeArtifact, and more.
---
# Using alternative package indexes
While uv uses the official Python Package Index (PyPI) by default, it also supports
[alternative package indexes](../../concepts/indexes.md). Most alternative indexes require various
forms of authentication, which require some initial setup.
!!! important
If using the pip interface, please read the documentation
on [using multiple indexes](../../pip/compatibility.md#packages-that-exist-on-multiple-indexes)
in uv — the default behavior is different from pip to prevent dependency confusion attacks, but
this means that uv may not find the versions of a package as you'd expect.
## Azure Artifacts
uv can install packages from
[Azure Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver),
either by using a
[Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows)
(PAT), or using the [`keyring`](https://github.com/jaraco/keyring) package.
To use Azure Artifacts, add the index to your project:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/"
```
### Authenticate with an Azure access token
If there is a personal access token (PAT) available (e.g.,
[`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)),
credentials can be provided via "Basic" HTTP authentication scheme. Include the PAT in the password
field of the URL. A username must be included as well, but can be any string.
For example, with the token stored in the `$AZURE_ARTIFACTS_TOKEN` environment variable, set
credentials for the index with:
```bash
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=dummy
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
```
!!! note
`PRIVATE_REGISTRY` should match the name of the index defined in your `pyproject.toml`.
### Authenticate with `keyring` and `artifacts-keyring`
You can also authenticate to Artifacts using [`keyring`](https://github.com/jaraco/keyring) package
with the [`artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because these
two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a
source other than Artifacts.
The `artifacts-keyring` plugin wraps the
[Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider). The
credential provider supports a few different authentication modes including interactive login — see
the [tool's documentation](https://github.com/microsoft/artifacts-credprovider) for information on
configuration.
uv only supports using the `keyring` package in
[subprocess mode](../../reference/settings.md#keyring-provider). The `keyring` executable must be in
the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a
username in the URL, and it must be `VssSessionToken`.
```bash
# Pre-install keyring and the Artifacts plugin from the public PyPI
uv tool install keyring --with artifacts-keyring
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
# Set the username for the index
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=VssSessionToken
```
!!! note
The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider)
setting can be used to enable keyring in your `uv.toml` or `pyproject.toml`.
Similarly, the username for the index can be added directly to the index URL.
### Publishing packages to Azure Artifacts
If you also want to publish your own packages to Azure Artifacts, you can use `uv publish` as
described in the [Building and publishing guide](../package.md).
First, add a `publish-url` to the index you want to publish packages to. For example:
```toml title="pyproject.toml" hl_lines="4"
[[tool.uv.index]]
name = "private-registry"
url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/"
publish-url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/"
```
Then, configure credentials (if not using keyring):
```console
$ export UV_PUBLISH_USERNAME=dummy
$ export UV_PUBLISH_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
```
And publish the package:
```console
$ uv publish --index private-registry
```
To use `uv publish` without adding the `publish-url` to the project, you can set `UV_PUBLISH_URL`:
```console
$ export UV_PUBLISH_URL=https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/
$ uv publish
```
Note this method is not preferable because uv cannot check if the package is already published
before uploading artifacts.
## Google Artifact Registry
uv can install packages from
[Google Artifact Registry](https://cloud.google.com/artifact-registry/docs), either by using an
access token, or using the [`keyring`](https://github.com/jaraco/keyring) package.
!!! note
This guide assumes that [`gcloud`](https://cloud.google.com/sdk/gcloud) CLI is installed and
authenticated.
To use Google Artifact Registry, add the index to your project:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
```
### Authenticate with a Google access token
Credentials can be provided via "Basic" HTTP authentication scheme. Include access token in the
password field of the URL. Username must be `oauth2accesstoken`, otherwise authentication will fail.
Generate a token with `gcloud`:
```bash
export ARTIFACT_REGISTRY_TOKEN=$(
gcloud auth application-default print-access-token
)
```
!!! note
You might need to pass extra parameters to properly generate the token (like `--project`), this
is a basic example.
Then set credentials for the index with:
```bash
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"
```
!!! note
`PRIVATE_REGISTRY` should match the name of the index defined in your `pyproject.toml`.
### Authenticate with `keyring` and `keyrings.google-artifactregistry-auth`
You can also authenticate to Artifact Registry using [`keyring`](https://github.com/jaraco/keyring)
package with the
[`keyrings.google-artifactregistry-auth` plugin](https://github.com/GoogleCloudPlatform/artifact-registry-python-tools).
Because these two packages are required to authenticate to Artifact Registry, they must be
pre-installed from a source other than Artifact Registry.
The `keyrings.google-artifactregistry-auth` plugin wraps
[gcloud CLI](https://cloud.google.com/sdk/gcloud) to generate short-lived access tokens, securely
store them in system keyring, and refresh them when they are expired.
uv only supports using the `keyring` package in
[subprocess mode](../../reference/settings.md#keyring-provider). The `keyring` executable must be in
the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a
username in the URL and it must be `oauth2accesstoken`.
```bash
# Pre-install keyring and Artifact Registry plugin from the public PyPI
uv tool install keyring --with keyrings.google-artifactregistry-auth
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
# Set the username for the index
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
```
!!! note
The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider)
setting can be used to enable keyring in your `uv.toml` or `pyproject.toml`.
Similarly, the username for the index can be added directly to the index URL.
### Publishing packages to Google Artifact Registry
If you also want to publish your own packages to Google Artifact Registry, you can use `uv publish`
as described in the [Building and publishing guide](../package.md).
First, add a `publish-url` to the index you want to publish packages to. For example:
```toml title="pyproject.toml" hl_lines="4"
[[tool.uv.index]]
name = "private-registry"
url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
publish-url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/"
```
Then, configure credentials (if not using keyring):
```console
$ export UV_PUBLISH_USERNAME=oauth2accesstoken
$ export UV_PUBLISH_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"
```
And publish the package:
```console
$ uv publish --index private-registry
```
To use `uv publish` without adding the `publish-url` to the project, you can set `UV_PUBLISH_URL`:
```console
$ export UV_PUBLISH_URL=https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/
$ uv publish
```
Note this method is not preferable because uv cannot check if the package is already published
before uploading artifacts.
## AWS CodeArtifact
uv can install packages from
[AWS CodeArtifact](https://docs.aws.amazon.com/codeartifact/latest/ug/using-python.html), either by
using an access token, or using the [`keyring`](https://github.com/jaraco/keyring) package.
!!! note
This guide assumes that [`awscli`](https://aws.amazon.com/cli/) is installed and authenticated.
The index can be declared like so:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"
```
### Authenticate with an AWS access token
Credentials can be provided via "Basic" HTTP authentication scheme. Include access token in the
password field of the URL. Username must be `aws`, otherwise authentication will fail.
Generate a token with `awscli`:
```bash
export AWS_CODEARTIFACT_TOKEN="$(
aws codeartifact get-authorization-token \
--domain <DOMAIN> \
--domain-owner <ACCOUNT_ID> \
--query authorizationToken \
--output text
)"
```
!!! note
You might need to pass extra parameters to properly generate the token (like `--region`), this
is a basic example.
Then set credentials for the index with:
```bash
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AWS_CODEARTIFACT_TOKEN"
```
!!! note
`PRIVATE_REGISTRY` should match the name of the index defined in your `pyproject.toml`.
### Authenticate with `keyring` and `keyrings.codeartifact`
You can also authenticate to Artifact Registry using [`keyring`](https://github.com/jaraco/keyring)
package with the [`keyrings.codeartifact` plugin](https://github.com/jmkeyes/keyrings.codeartifact).
Because these two packages are required to authenticate to Artifact Registry, they must be
pre-installed from a source other than Artifact Registry.
The `keyrings.codeartifact` plugin wraps [boto3](https://pypi.org/project/boto3/) to generate
short-lived access tokens, securely store them in system keyring, and refresh them when they are
expired.
uv only supports using the `keyring` package in
[subprocess mode](../../reference/settings.md#keyring-provider). The `keyring` executable must be in
the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a
username in the URL and it must be `aws`.
```bash
# Pre-install keyring and AWS CodeArtifact plugin from the public PyPI
uv tool install keyring --with keyrings.codeartifact
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
# Set the username for the index
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws
```
!!! note
The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider)
setting can be used to enable keyring in your `uv.toml` or `pyproject.toml`.
Similarly, the username for the index can be added directly to the index URL.
### Publishing packages to AWS CodeArtifact
If you also want to publish your own packages to AWS CodeArtifact, you can use `uv publish` as
described in the [Building and publishing guide](../package.md).
First, add a `publish-url` to the index you want to publish packages to. For example:
```toml title="pyproject.toml" hl_lines="4"
[[tool.uv.index]]
name = "private-registry"
url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"
publish-url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/"
```
Then, configure credentials (if not using keyring):
```console
$ export UV_PUBLISH_USERNAME=aws
$ export UV_PUBLISH_PASSWORD="$AWS_CODEARTIFACT_TOKEN"
```
And publish the package:
```console
$ uv publish --index private-registry
```
To use `uv publish` without adding the `publish-url` to the project, you can set `UV_PUBLISH_URL`:
```console
$ export UV_PUBLISH_URL=https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/
$ uv publish
```
Note this method is not preferable because uv cannot check if the package is already published
before uploading artifacts.
## JFrog Artifactory
uv can install packages from JFrog Artifactory, either by using a username and password or a JWT
token.
To use it, add the index to your project:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple"
```
### Authenticate with username and password
```console
$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME="<username>"
$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="<password>"
```
### Authenticate with JWT token
```console
$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME=""
$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$JFROG_JWT_TOKEN"
```
!!! note
Replace `PRIVATE_REGISTRY` in the environment variable names with the actual index name defined in your `pyproject.toml`.
### Publishing packages to JFrog Artifactory
Add a `publish-url` to your index definition:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple"
publish-url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>"
```
!!! important
If you use `--token "$JFROG_TOKEN"` or `UV_PUBLISH_TOKEN` with JFrog, you will receive a
401 Unauthorized error as JFrog requires an empty username but uv passes `__token__` for as
the username when `--token` is used.
To authenticate, pass your token as the password and set the username to an empty string:
```console
$ uv publish --index <index_name> -u "" -p "$JFROG_TOKEN"
```
Alternatively, you can set environment variables:
```console
$ export UV_PUBLISH_USERNAME=""
$ export UV_PUBLISH_PASSWORD="$JFROG_TOKEN"
$ uv publish --index private-registry
```
!!! note
The publish environment variables (`UV_PUBLISH_USERNAME` and `UV_PUBLISH_PASSWORD`) do not include the index name.
docs/guides/integration/aws.md
+126
View File
@@ -0,0 +1,126 @@
---
title: AWS CodeArtifact
description: Using uv with AWS CodeArtifact for installing and publishing Python packages.
---
# AWS CodeArtifact
uv can install packages from
[AWS CodeArtifact](https://docs.aws.amazon.com/codeartifact/latest/ug/using-python.html), either by
using an access token, or using the [`keyring`](https://github.com/jaraco/keyring) package.
!!! note
This guide assumes that [`awscli`](https://aws.amazon.com/cli/) is installed and authenticated.
The index can be declared like so:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"
```
## Authenticate with an AWS access token
Credentials can be provided via "Basic" HTTP authentication scheme. Include access token in the
password field of the URL. Username must be `aws`, otherwise authentication will fail.
Generate a token with `awscli`:
```bash
export AWS_CODEARTIFACT_TOKEN="$(
aws codeartifact get-authorization-token \
--domain <DOMAIN> \
--domain-owner <ACCOUNT_ID> \
--query authorizationToken \
--output text
)"
```
!!! note
You might need to pass extra parameters to properly generate the token (like `--region`), this
is a basic example.
Then set credentials for the index with:
```bash
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AWS_CODEARTIFACT_TOKEN"
```
!!! note
`PRIVATE_REGISTRY` should match the name of the index defined in your `pyproject.toml`.
## Authenticate with `keyring` and `keyrings.codeartifact`
You can also authenticate to Artifact Registry using [`keyring`](https://github.com/jaraco/keyring)
package with the [`keyrings.codeartifact` plugin](https://github.com/jmkeyes/keyrings.codeartifact).
Because these two packages are required to authenticate to Artifact Registry, they must be
pre-installed from a source other than Artifact Registry.
The `keyrings.codeartifact` plugin wraps [boto3](https://pypi.org/project/boto3/) to generate
short-lived access tokens, securely store them in system keyring, and refresh them when they are
expired.
uv only supports using the `keyring` package in
[subprocess mode](../../reference/settings.md#keyring-provider). The `keyring` executable must be in
the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a
username in the URL and it must be `aws`.
```bash
# Pre-install keyring and AWS CodeArtifact plugin from the public PyPI
uv tool install keyring --with keyrings.codeartifact
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
# Set the username for the index
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws
```
!!! note
The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider)
setting can be used to enable keyring in your `uv.toml` or `pyproject.toml`.
Similarly, the username for the index can be added directly to the index URL.
## Publishing packages
If you also want to publish your own packages to AWS CodeArtifact, you can use `uv publish` as
described in the [Building and publishing guide](../package.md).
First, add a `publish-url` to the index you want to publish packages to. For example:
```toml title="pyproject.toml" hl_lines="4"
[[tool.uv.index]]
name = "private-registry"
url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"
publish-url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/"
```
Then, configure credentials (if not using keyring):
```console
$ export UV_PUBLISH_USERNAME=aws
$ export UV_PUBLISH_PASSWORD="$AWS_CODEARTIFACT_TOKEN"
```
And publish the package:
```console
$ uv publish --index private-registry
```
To use `uv publish` without adding the `publish-url` to the project, you can set `UV_PUBLISH_URL`:
```console
$ export UV_PUBLISH_URL=https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/
$ uv publish
```
Note this method is not preferable because uv cannot check if the package is already published
before uploading artifacts.
docs/guides/integration/azure.md
+112
View File
@@ -0,0 +1,112 @@
---
title: Azure Artifacts
description: Using uv with Azure Artifacts for installing and publishing Python packages.
---
# Azure Artifacts
uv can install packages from
[Azure Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver),
either by using a
[Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows)
(PAT), or using the [`keyring`](https://github.com/jaraco/keyring) package.
To use Azure Artifacts, add the index to your project:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/"
```
## Authenticate with an Azure access token
If there is a personal access token (PAT) available (e.g.,
[`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)),
credentials can be provided via "Basic" HTTP authentication scheme. Include the PAT in the password
field of the URL. A username must be included as well, but can be any string.
For example, with the token stored in the `$AZURE_ARTIFACTS_TOKEN` environment variable, set
credentials for the index with:
```bash
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=dummy
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
```
!!! note
`PRIVATE_REGISTRY` should match the name of the index defined in your `pyproject.toml`.
## Authenticate with `keyring` and `artifacts-keyring`
You can also authenticate to Artifacts using [`keyring`](https://github.com/jaraco/keyring) package
with the [`artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because these
two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a
source other than Artifacts.
The `artifacts-keyring` plugin wraps the
[Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider). The
credential provider supports a few different authentication modes including interactive login — see
the [tool's documentation](https://github.com/microsoft/artifacts-credprovider) for information on
configuration.
uv only supports using the `keyring` package in
[subprocess mode](../../reference/settings.md#keyring-provider). The `keyring` executable must be in
the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a
username in the URL, and it must be `VssSessionToken`.
```bash
# Pre-install keyring and the Artifacts plugin from the public PyPI
uv tool install keyring --with artifacts-keyring
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
# Set the username for the index
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=VssSessionToken
```
!!! note
The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider)
setting can be used to enable keyring in your `uv.toml` or `pyproject.toml`.
Similarly, the username for the index can be added directly to the index URL.
## Publishing packages
If you also want to publish your own packages to Azure Artifacts, you can use `uv publish` as
described in the [Building and publishing guide](../package.md).
First, add a `publish-url` to the index you want to publish packages to. For example:
```toml title="pyproject.toml" hl_lines="4"
[[tool.uv.index]]
name = "private-registry"
url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/"
publish-url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/"
```
Then, configure credentials (if not using keyring):
```console
$ export UV_PUBLISH_USERNAME=dummy
$ export UV_PUBLISH_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
```
And publish the package:
```console
$ uv publish --index private-registry
```
To use `uv publish` without adding the `publish-url` to the project, you can set `UV_PUBLISH_URL`:
```console
$ export UV_PUBLISH_URL=https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/
$ uv publish
```
Note this method is not preferable because uv cannot check if the package is already published
before uploading artifacts.
docs/guides/integration/google.md
+124
View File
@@ -0,0 +1,124 @@
---
title: Google Artifact Registry
description: Using uv with Google Artifact Registry for installing and publishing Python packages.
---
# Google Artifact Registry
uv can install packages from
[Google Artifact Registry](https://cloud.google.com/artifact-registry/docs), either by using an
access token, or using the [`keyring`](https://github.com/jaraco/keyring) package.
!!! note
This guide assumes that [`gcloud`](https://cloud.google.com/sdk/gcloud) CLI is installed and
authenticated.
To use Google Artifact Registry, add the index to your project:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
```
## Authenticate with a Google access token
Credentials can be provided via "Basic" HTTP authentication scheme. Include access token in the
password field of the URL. Username must be `oauth2accesstoken`, otherwise authentication will fail.
Generate a token with `gcloud`:
```bash
export ARTIFACT_REGISTRY_TOKEN=$(
gcloud auth application-default print-access-token
)
```
!!! note
You might need to pass extra parameters to properly generate the token (like `--project`), this
is a basic example.
Then set credentials for the index with:
```bash
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"
```
!!! note
`PRIVATE_REGISTRY` should match the name of the index defined in your `pyproject.toml`.
## Authenticate with `keyring` and `keyrings.google-artifactregistry-auth`
You can also authenticate to Artifact Registry using [`keyring`](https://github.com/jaraco/keyring)
package with the
[`keyrings.google-artifactregistry-auth` plugin](https://github.com/GoogleCloudPlatform/artifact-registry-python-tools).
Because these two packages are required to authenticate to Artifact Registry, they must be
pre-installed from a source other than Artifact Registry.
The `keyrings.google-artifactregistry-auth` plugin wraps
[gcloud CLI](https://cloud.google.com/sdk/gcloud) to generate short-lived access tokens, securely
store them in system keyring, and refresh them when they are expired.
uv only supports using the `keyring` package in
[subprocess mode](../../reference/settings.md#keyring-provider). The `keyring` executable must be in
the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a
username in the URL and it must be `oauth2accesstoken`.
```bash
# Pre-install keyring and Artifact Registry plugin from the public PyPI
uv tool install keyring --with keyrings.google-artifactregistry-auth
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
# Set the username for the index
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
```
!!! note
The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider)
setting can be used to enable keyring in your `uv.toml` or `pyproject.toml`.
Similarly, the username for the index can be added directly to the index URL.
## Publishing packages
If you also want to publish your own packages to Google Artifact Registry, you can use `uv publish`
as described in the [Building and publishing guide](../package.md).
First, add a `publish-url` to the index you want to publish packages to. For example:
```toml title="pyproject.toml" hl_lines="4"
[[tool.uv.index]]
name = "private-registry"
url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
publish-url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/"
```
Then, configure credentials (if not using keyring):
```console
$ export UV_PUBLISH_USERNAME=oauth2accesstoken
$ export UV_PUBLISH_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"
```
And publish the package:
```console
$ uv publish --index private-registry
```
To use `uv publish` without adding the `publish-url` to the project, you can set `UV_PUBLISH_URL`:
```console
$ export UV_PUBLISH_URL=https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/
$ uv publish
```
Note this method is not preferable because uv cannot check if the package is already published
before uploading artifacts.
docs/guides/integration/index.md
+4 -1
View File
@@ -8,9 +8,12 @@ Learn how to integrate uv with other software:
- [Using with pre-commit](./pre-commit.md)
- [Using in GitHub Actions](./github.md)
- [Using in GitLab CI/CD](./gitlab.md)
- [Using with alternative package indexes](./alternative-indexes.md)
- [Installing PyTorch](./pytorch.md)
- [Building a FastAPI application](./fastapi.md)
- [Using with Azure Artifacts](./azure.md)
- [Using with Google Artifact Registry](./google.md)
- [Using with AWS CodeArtifact](./aws.md)
- [Using with JFrog Artifactory](./jfrog.md)
- [Using with Renovate](./renovate.md)
- [Using with Dependabot](./dependabot.md)
- [Using with AWS Lambda](./aws-lambda.md)
docs/guides/integration/jfrog.md
+70
View File
@@ -0,0 +1,70 @@
---
title: JFrog Artifactory
description: Using uv with JFrog Artifactory for installing and publishing Python packages.
---
# JFrog Artifactory
uv can install packages from JFrog Artifactory, either by using a username and password or a JWT
token.
To use it, add the index to your project:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple"
```
## Authenticate with username and password
```console
$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME="<username>"
$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="<password>"
```
## Authenticate with JWT token
```console
$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME=""
$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$JFROG_JWT_TOKEN"
```
!!! note
Replace `PRIVATE_REGISTRY` in the environment variable names with the actual index name defined in your `pyproject.toml`.
## Publishing packages
Add a `publish-url` to your index definition:
```toml title="pyproject.toml"
[[tool.uv.index]]
name = "private-registry"
url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple"
publish-url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>"
```
!!! important
If you use `--token "$JFROG_TOKEN"` or `UV_PUBLISH_TOKEN` with JFrog, you will receive a
401 Unauthorized error as JFrog requires an empty username but uv passes `__token__` for as
the username when `--token` is used.
To authenticate, pass your token as the password and set the username to an empty string:
```console
$ uv publish --index <index_name> -u "" -p "$JFROG_TOKEN"
```
Alternatively, you can set environment variables:
```console
$ export UV_PUBLISH_USERNAME=""
$ export UV_PUBLISH_PASSWORD="$JFROG_TOKEN"
$ uv publish --index private-registry
```
!!! note
The publish environment variables (`UV_PUBLISH_USERNAME` and `UV_PUBLISH_PASSWORD`) do not include the index name.
mkdocs.yml
+9 -2
View File
@@ -84,6 +84,7 @@ plugins:
"configuration/environment.md": "reference/environment.md"
"guides/export.md": "concepts/projects/export.md"
"guides/integration/dependency-bots.md": "guides/integration/renovate.md"
"guides/integration/alternative-indexes.md": "concepts/authentication/third-party.md"
- llmstxt:
markdown_description: |
You can use uv to install Python dependencies, run scripts, manage virtual environments,
@@ -117,7 +118,10 @@ plugins:
- guides/integration/pre-commit.md
- guides/integration/pytorch.md
- guides/integration/fastapi.md
- guides/integration/alternative-indexes.md
- guides/integration/azure.md
- guides/integration/google.md
- guides/integration/aws.md
- guides/integration/jfrog.md
- guides/integration/renovate.md
- guides/integration/dependabot.md
- guides/integration/aws-lambda.md
@@ -199,7 +203,10 @@ nav:
- Pre-commit: guides/integration/pre-commit.md
- PyTorch: guides/integration/pytorch.md
- FastAPI: guides/integration/fastapi.md
- Alternative indexes: guides/integration/alternative-indexes.md
- Azure Artifacts: guides/integration/azure.md
- Google Artifact Registry: guides/integration/google.md
- AWS CodeArtifact: guides/integration/aws.md
- JFrog Artifactory: guides/integration/jfrog.md
- Renovate: guides/integration/renovate.md
- Dependabot: guides/integration/dependabot.md
- AWS Lambda: guides/integration/aws-lambda.md