> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/python-pypi.md).

# Python

Python / PyPI - publish packages to Harness Artifacts

Use a **Python / PyPI** registry to host private Python packages, compatible with pip, Poetry, and uv.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install pip, Poetry, or uv on your local machine, depending on the tool you use to manage Python packages.
* If you publish with pip, install the `build` and `twine` Python packages (`pip install build twine`).
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Python registry

To create a Python registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Python** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Python packages from PyPI or another PyPI-compatible index when they are not available locally. The default upstream is PyPI (`pypi.org`).

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Python** as the **Registry type**.
7. Select the **Source**: **PyPI** or **Custom**.
   * If you select **PyPI**, optionally specify a **Custom registry suffix**.
   * If you select **Custom**, specify the **Remote registry URL**.
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required.
9. Optionally, configure **Metadata configuration**:
   * **Metadata cache TTL (seconds)**: How long Harness caches package metadata from the upstream before it checks the upstream again.
   * **Negative cache TTL (seconds)**: How long Harness caches a failed lookup before it retries the upstream.
10. Select **Create** to finalize.

{% hint style="info" %}
**Custom registry suffix**

Specify a custom registry suffix when a PyPI-compatible index, such as Artifactory, Nexus, or a private PyPI mirror, does not serve packages at the default `/simple/` endpoint.
{% endhint %}

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Python / PyPI Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from PyPI or the configured upstream and caches it.
{% endhint %}

## Python / PyPI client setup

In your Python / PyPI Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for pip, Poetry, or uv.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Python / PyPI Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Select **pip**, **Poetry**, or **uv** for your client. In the code samples, replace the values in angle brackets with your own values.

{% tabs %}
{% tab title="pip" %}
**1. Configure \~/.pypirc**

Add the following to `~/.pypirc`:

```ini
[distutils]
index-servers = harness

[harness]
repository = https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/python
username = <YOUR_EMAIL>
password = <IDENTITY_TOKEN>
```

**2. Publish the package**

Build and publish your package:

```bash
python -m build
python -m twine upload --repository harness /path/to/files/*
```

**3. Use the package**

Install the package with pip:

```bash
pip install --index-url https://<YOUR_EMAIL>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/python/simple --no-deps <ARTIFACT_NAME>==<VERSION>
```

{% endtab %}

{% tab title="Poetry" %}
**1. Configure the source**

Add the registry as a source and configure authentication:

```bash
poetry source add --priority=explicit harness https://<YOUR_EMAIL>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/python/simple/
poetry config http-basic.harness <YOUR_EMAIL> <IDENTITY_TOKEN>
```

**2. Publish the package**

Configure the publish repository and publish your package:

```bash
poetry config repositories.harness https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/python
poetry build
poetry publish --repository harness
```

**3. Use the package**

Add the package to your project with Poetry:

```bash
poetry add --source harness <ARTIFACT_NAME>==<VERSION>
```

{% endtab %}

{% tab title="uv" %}
**1. Publish the package**

Build and publish your package:

```bash
uv build
uv publish --publish-url https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/python --username <YOUR_EMAIL> --password <IDENTITY_TOKEN>
```

**2. Use the package**

Install the package with uv:

```bash
uv pip install --index-url https://<YOUR_EMAIL>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/python/simple --no-deps <ARTIFACT_NAME>==<VERSION>
```

{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new directory with no pip cache, Poetry cache, or uv cache for the package, use your package client to install the package you published.
2. Confirm that the client downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step sets the package version from the tag, then builds and publishes it with pip and twine. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        sed -i "s/^version = .*/version = \"$PACKAGE_VERSION\"/" pyproject.toml
        python -m build
        python -m twine upload --repository harness dist/*
```

## Troubleshooting

<details>

<summary>`twine upload` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that the `username` and `password` in `~/.pypirc`, or the credentials passed to `poetry config` or `uv publish`, match your Harness email and the identity token you generated in **Setup Client**. If the token expired or was revoked, generate a new one and update your client configuration.

</details>

<details>

<summary>`twine upload` returns `409 Conflict` or `400 File already exists`</summary>

Package versions are immutable after publish. Bump the version in `pyproject.toml` or `setup.py`, and publish again. Delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`pip install` cannot find the package, or resolves an old version</summary>

Check that the artifact name and version match the values you used to publish, and that the registry name and account ID in the index URL are correct. If pip resolves an older version, clear the local cache with `pip cache purge` and reinstall.

</details>

<details>

<summary>`poetry add` or `uv pip install` cannot authenticate to the registry</summary>

Check that `poetry config http-basic.harness`, or the `--username` and `--password` flags for uv, reference the same email and identity token configured in **Setup Client**. Run `poetry config --list` to confirm the stored credentials.

</details>

<details>

<summary>Setup Client omits publish instructions for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** shows only install instructions. To publish your own packages, create a separate, non-upstream registry, or add the upstream proxy to a registry that also accepts uploads.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
