diff --git a/docs/guides/integration/alternative-indexes.md b/docs/guides/integration/alternative-indexes.md index 0492de87b..440441367 100644 --- a/docs/guides/integration/alternative-indexes.md +++ b/docs/guides/integration/alternative-indexes.md @@ -7,108 +7,189 @@ description: # Using alternative package indexes -While uv uses the official Python Package Index (PyPI) by default, it also supports alternative -package indexes. Most alternative indexes require various forms of authentication, which requires -some initial setup. +While uv uses the official Python Package Index (PyPI) by default, it also supports +[alternative package indexes](../../configuration/indexes.md). Most alternative indexes require +various forms of authentication, which require some initial setup. !!! important - Please read the documentation on [using multiple indexes](../../pip/compatibility.md#packages-that-exist-on-multiple-indexes) + 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 DevOps Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). -Authenticate to a feed using a +[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 interactively using the [`keyring`](https://github.com/jaraco/keyring) package. +(PAT), or using the [`keyring`](https://github.com/jaraco/keyring) package. -### Using a PAT +To use Azure Artifacts, add the index to your project: -If there is a PAT available (eg -[`$(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 the "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 `$ADO_PAT` environment variable, set the index URL with: - -```console -$ export UV_INDEX=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/ +```toml title="pyproject.toml" +[[tool.uv.index]] +name = "private-registry" +url = "https://pkgs.dev.azure.com///_packaging//pypi/simple/" ``` -### Using `keyring` +### Authenticate with an Azure access token -If there is not a PAT available, authenticate to Artifacts using the -[`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. +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. -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. +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](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). -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, so the index URL must include the -default username `VssSessionToken`. +[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--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///_packaging//pypi/simple/" +publish-url = "https://pkgs.dev.azure.com///_packaging//pypi/upload/" +``` + +Then, configure credentials (if not using keyring): ```console -$ # 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 - -$ # Configure the index URL with the username -$ export UV_INDEX=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/ +$ 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///_packaging//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). Authenticate to a -repository using password authentication or using [`keyring`](https://github.com/jaraco/keyring) -package. +[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 `gcloud` CLI has previously been installed and setup. + This guide assumes that [`gcloud`](https://cloud.google.com/sdk/gcloud) CLI is installed and + authenticated. -### Password authentication +To use Google Artifact Registry, add the index to your project: + +```toml title="pyproject.toml" +[[tool.uv.index]] +name = "private-registry" +url = "https://-python.pkg.dev//" +``` + +### 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. -For example, with the token stored in the `$ARTIFACT_REGISTRY_TOKEN` environment variable, set the -index URL with: +Generate a token with `gcloud`: ```bash -export ARTIFACT_REGISTRY_TOKEN=$(gcloud auth application-default print-access-token) -export UV_INDEX=https://oauth2accesstoken:$ARTIFACT_REGISTRY_TOKEN@{region}-python.pkg.dev/{projectId}/{repositoryName}/simple +export ARTIFACT_REGISTRY_TOKEN=$( + gcloud auth application-default print-access-token +) ``` -### Using `keyring` +!!! 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 +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 `artifacts-keyring` 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. +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](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). -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`. +[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 @@ -117,64 +198,176 @@ uv tool install keyring --with keyrings.google-artifactregistry-auth # Enable keyring authentication export UV_KEYRING_PROVIDER=subprocess -# Configure the index URL with the username -export UV_INDEX=https://oauth2accesstoken@{region}-python.pkg.dev/{projectId}/{repositoryName}/simple +# Set the username for the index +export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken ``` +!!! note + + The [`tool.uv.keyring-provider`](../../reference/settings.md#keyring-provider--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://-python.pkg.dev//" +publish-url = "https://-python.pkg.dev//" +``` + +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://-python.pkg.dev// +$ 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). - -The authorization token can be retrieved using the `awscli` tool. +[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 the AWS CLI has previously been authenticated. + This guide assumes that [`awscli`](https://aws.amazon.com/cli/) is installed and authenticated. -First, declare some constants for your CodeArtifact repository: +The index can be declared like so: -```bash -export AWS_DOMAIN="" -export AWS_ACCOUNT_ID="" -export AWS_REGION="" -export AWS_CODEARTIFACT_REPOSITORY="" +```toml title="pyproject.toml" +[[tool.uv.index]] +name = "private-registry" +url = "https://-.d.codeartifact..amazonaws.com/pypi//simple/" ``` -Then, retrieve a token from the `awscli`: +### 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 $AWS_DOMAIN \ - --domain-owner $AWS_ACCOUNT_ID \ + --domain \ + --domain-owner \ --query authorizationToken \ --output text )" ``` -And configure the index URL: +!!! 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="https://aws:${AWS_CODEARTIFACT_TOKEN}@${AWS_DOMAIN}-${AWS_ACCOUNT_ID}.d.codeartifact.${AWS_REGION}.amazonaws.com/pypi/${AWS_CODEARTIFACT_REPOSITORY}/simple/" +export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws +export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AWS_CODEARTIFACT_TOKEN" ``` -### Publishing packages +!!! 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--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 [publishing guide](../package.md). You will need to set `UV_PUBLISH_URL` separately -from the credentials: +described in the [Building and publishing guide](../package.md). -```bash -# Configure uv to use AWS CodeArtifact -export UV_PUBLISH_URL="https://${AWS_DOMAIN}-${AWS_ACCOUNT_ID}.d.codeartifact.${AWS_REGION}.amazonaws.com/pypi/${AWS_CODEARTIFACT_REPOSITORY}/" -export UV_PUBLISH_USERNAME=aws -export UV_PUBLISH_PASSWORD="$AWS_CODEARTIFACT_TOKEN" +First, add a `publish-url` to the index you want to publish packages to. For example: -# Publish the package -uv publish +```toml title="pyproject.toml" hl_lines="4" +[[tool.uv.index]] +name = "private-registry" +url = "https://-.d.codeartifact..amazonaws.com/pypi//simple/" +publish-url = "https://-.d.codeartifact..amazonaws.com/pypi//" ``` -## Other indexes +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://-.d.codeartifact..amazonaws.com/pypi// +$ uv publish +``` + +Note this method is not preferable because uv cannot check if the package is already published +before uploading artifacts. + +## Other package indexes uv is also known to work with JFrog's Artifactory.