diff --git a/docs/concepts/authentication/third-party.md b/docs/concepts/authentication/third-party.md index de9cb2fef12ef..7d4ac0c0c2e27 100644 --- a/docs/concepts/authentication/third-party.md +++ b/docs/concepts/authentication/third-party.md @@ -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 diff --git a/docs/concepts/indexes.md b/docs/concepts/indexes.md index 7dca6ea147e11..9d788db262ca4 100644 --- a/docs/concepts/indexes.md +++ b/docs/concepts/indexes.md @@ -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 diff --git a/docs/guides/integration/alternative-indexes.md b/docs/guides/integration/alternative-indexes.md deleted file mode 100644 index 3e73efff0e04b..0000000000000 --- a/docs/guides/integration/alternative-indexes.md +++ /dev/null @@ -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///_packaging//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///_packaging//pypi/simple/" -publish-url = "https://pkgs.dev.azure.com///_packaging//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///_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), 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://-python.pkg.dev///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://-python.pkg.dev///simple/" -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), 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://-.d.codeartifact..amazonaws.com/pypi//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-owner \ - --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://-.d.codeartifact..amazonaws.com/pypi//simple/" -publish-url = "https://-.d.codeartifact..amazonaws.com/pypi//" -``` - -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. - -## 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://.jfrog.io/artifactory/api/pypi//simple" -``` - -### Authenticate with username and password - -```console -$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME="" -$ export UV_INDEX_PRIVATE_REGISTRY_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://.jfrog.io/artifactory/api/pypi//simple" -publish-url = "https://.jfrog.io/artifactory/api/pypi/" -``` - -!!! 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 -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. diff --git a/docs/guides/integration/aws.md b/docs/guides/integration/aws.md new file mode 100644 index 0000000000000..1dacec3605ffe --- /dev/null +++ b/docs/guides/integration/aws.md @@ -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://-.d.codeartifact..amazonaws.com/pypi//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-owner \ + --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://-.d.codeartifact..amazonaws.com/pypi//simple/" +publish-url = "https://-.d.codeartifact..amazonaws.com/pypi//" +``` + +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. diff --git a/docs/guides/integration/azure.md b/docs/guides/integration/azure.md new file mode 100644 index 0000000000000..bf39efb679a47 --- /dev/null +++ b/docs/guides/integration/azure.md @@ -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///_packaging//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///_packaging//pypi/simple/" +publish-url = "https://pkgs.dev.azure.com///_packaging//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///_packaging//pypi/upload/ +$ uv publish +``` + +Note this method is not preferable because uv cannot check if the package is already published +before uploading artifacts. diff --git a/docs/guides/integration/google.md b/docs/guides/integration/google.md new file mode 100644 index 0000000000000..d75a60e3bc892 --- /dev/null +++ b/docs/guides/integration/google.md @@ -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://-python.pkg.dev///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://-python.pkg.dev///simple/" +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. diff --git a/docs/guides/integration/index.md b/docs/guides/integration/index.md index 3b2c336449b6a..d7b7c70a96e7c 100644 --- a/docs/guides/integration/index.md +++ b/docs/guides/integration/index.md @@ -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) diff --git a/docs/guides/integration/jfrog.md b/docs/guides/integration/jfrog.md new file mode 100644 index 0000000000000..44df8b052b04b --- /dev/null +++ b/docs/guides/integration/jfrog.md @@ -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://.jfrog.io/artifactory/api/pypi//simple" +``` + +## Authenticate with username and password + +```console +$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME="" +$ export UV_INDEX_PRIVATE_REGISTRY_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://.jfrog.io/artifactory/api/pypi//simple" +publish-url = "https://.jfrog.io/artifactory/api/pypi/" +``` + +!!! 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 -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. diff --git a/mkdocs.yml b/mkdocs.yml index 7213606ad9094..58a584ed3c6b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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