Pulling a Python package from a Cloud Registry

Written by

Yandex Cloud

Updated at May 26, 2026

Installation from different registry types
Installing packages with dependencies from different sources

To pull a Python package, you need the cloud-registry.artifacts.puller role or higher.

pip

Poetry

Set authentication variables:

export IAM_TOKEN="<IAM_token>"
export LOCAL_REG_ID="<registry_ID>"   
export REMOTE_REG_ID="<remote_registry_ID>"  
export VIRTUAL_REG_ID="<virtual_registry_ID>"

Pull a Python package from a registry:

pip install <package_name> \
  --index-url https://iam:$IAM_TOKEN@registry.yandexcloud.net/pypi/$LOCAL_REG_ID/simple/

Where:

$IAM_TOKEN: IAM token being used for authentication.
<registry_ID>: Your registry ID.
<package_name>: Name of the package being installed.

Result:

Collecting my_package
  Downloading https://registry.yandexcloud.net/pypi/e5o6a2blpkb6********/simple/my-package/my_package-0.0.1-py3-none-any.whl (4.5 kB)
Installing collected packages: my_package
Successfully installed my_package-0.0.1

Make sure the package was installed:

python3 -m pip list | grep my_package

Result:

my_package    0.0.1

Set authentication variables:

export IAM_TOKEN="<IAM_token>"
export LOCAL_REG_ID="<registry_ID>"   
export REMOTE_REG_ID="<remote_registry_ID>"  
export VIRTUAL_REG_ID="<virtual_registry_ID>"

Add the package source:

poetry config http-basic.cloud-registry iam $IAM_TOKEN
poetry init  # Press Enter for all questions
poetry source add cloud-registry https://iam:$IAM_TOKEN@registry.yandexcloud.net/pypi/$LOCAL_REG_ID/simple/

Download a package:

poetry add <package_name> --source cloud-registry

Result:

Using version ^0.0.1 for my_package

Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 1 install, 0 updates, 0 removals

  - Installing my_package (0.0.1)

Writing lock file

Set authentication variables:

export IAM_TOKEN="<IAM_token>"
export LOCAL_REG_ID="<registry_ID>"   
export REMOTE_REG_ID="<remote_registry_ID>"  
export VIRTUAL_REG_ID="<virtual_registry_ID>"

Download a package:

uv pip install <package_name> \
  --index-url https://iam:$IAM_TOKEN@registry.yandexcloud.net/pypi/$LOCAL_REG_ID/simple/

Result:

Resolved 1 package in 0.5s
Downloaded 1 package in 0.2s
Installed 1 package in 0.1s
 + my_package==0.0.1

Installation from different registry types

Local registry

A local registry contains packages created and published within your organization.

Create the following environment variables depending on the authentication method:
IAM token

OAuth token

API key
1. Get an IAM token for the Yandex account or service account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="iam" export REGISTRY_PASSWORD="<IAM_token>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously obtained IAM token.
Note

The IAM token's lifetime is limited to 12 hours.
1. Get an OAuth token for the Yandex account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="oauth" export REGISTRY_PASSWORD="<OAuth_token>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously obtained OAuth token.
Note

The OAuth token is valid for one year.
1. Create an API key for the service account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="api_key" export REGISTRY_PASSWORD="<API_key>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously created API key.
Note

The API key maximum lifetime is set manually when you create the key.

Install a package from a local registry:

IAM token

API key

pip install <package_name> \
  --index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --no-cache

Where:

<registry_ID>: Your local registry ID.
<package_name>: Name of the package being installed.

pip install <package_name> \
  --index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --no-cache

Where:

<registry_ID>: Your local registry ID.
<package_name>: Name of the package being installed.

Example:

pip install <package_name> \
  --index-url https://iam:$(yc iam create-token)@registry.yandexcloud.net/pypi/e5o6a2blpkb6********/simple/

Remote registry

A remote registry acts as a proxy for public repositories such as PyPI. Remote registries cache packages locally after the first request.

Create the following environment variables depending on the authentication method:
IAM token

OAuth token

API key
1. Get an IAM token for the Yandex account or service account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="iam" export REGISTRY_PASSWORD="<IAM_token>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously obtained IAM token.
Note

The IAM token's lifetime is limited to 12 hours.
1. Get an OAuth token for the Yandex account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="oauth" export REGISTRY_PASSWORD="<OAuth_token>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously obtained OAuth token.
Note

The OAuth token is valid for one year.
1. Create an API key for the service account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="api_key" export REGISTRY_PASSWORD="<API_key>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously created API key.
Note

The API key maximum lifetime is set manually when you create the key.

Install a package from a remote registry:

IAM token

API key

pip install <package_name> \
  --index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --no-cache

Where:

<registry_ID>: Your remote registry's ID.
<package_name>: Name of the package being installed from the public PyPI.

pip install <package_name> \
  --index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --no-cache

Where:

<registry_ID>: Your remote registry's ID.
<package_name>: Name of the package being installed from the public PyPI.

Example:

pip install pytest==9.0.1 \
  --index-url https://iam:$(yc iam create-token)@registry.yandexcloud.net/pypi/e5o6a2blpkb6********/simple/

Upon the first request, the package will be uploaded from the public PyPI and stored in the cache. During subsequent installations, the package will be loaded from the cache.

Virtual registry

A virtual registry combines several local and remote registries under a single name, providing a single entry point for searching and installing packages.

Create the following environment variables depending on the authentication method:
IAM token

OAuth token

API key
1. Get an IAM token for the Yandex account or service account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="iam" export REGISTRY_PASSWORD="<IAM_token>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously obtained IAM token.
Note

The IAM token's lifetime is limited to 12 hours.
1. Get an OAuth token for the Yandex account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="oauth" export REGISTRY_PASSWORD="<OAuth_token>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously obtained OAuth token.
Note

The OAuth token is valid for one year.
1. Create an API key for the service account you are going to use for authentication.
2. Create the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables:
  export REGISTRY_USERNAME="api_key" export REGISTRY_PASSWORD="<API_key>"
  Where:
  - REGISTRY_USERNAME: Authentication method.
  - REGISTRY_PASSWORD: Body of the previously created API key.
Note

The API key maximum lifetime is set manually when you create the key.

Install a package from a virtual registry:

IAM token

API key

pip install <package_name> \
  --index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --no-cache

Where:

<registry_ID>: Your virtual registry's ID.
<package_name>: Name of the package being installed.

pip install <package_name> \
  --index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --no-cache

Where:

<registry_ID>: Your virtual registry's ID.
<package_name>: Name of the package being installed.

Example:

pip install <package_name> \
  --index-url https://iam:$(yc iam create-token)@registry.yandexcloud.net/pypi/e5o6a2blpkb6********/simple/

The virtual registry automatically searches for the package in all connected local and remote registries according to their priority order.

Installing packages with dependencies from different sources

If you need to install a package from your own registry while its dependencies come from the public PyPI, use the --extra-index-url parameter:

pip install <package_name> \
  --index-url https://iam:$(yc iam create-token)@registry.yandexcloud.net/pypi/<registry_ID>/simple/ \
  --extra-index-url https://pypi.org/simple/

Where:

--index-url: Primary package source (your registry).
--extra-index-url: Additional source for dependencies (public PyPI).

Pulling a Python package from a Cloud Registry

Installation from different registry types

Local registry

Remote registry

Virtual registry

Installing packages with dependencies from different sources

See also

Was the article helpful?

Pulling a Python package from a Cloud Registry

Installation from different registry typesInstallation from different registry types

Local registryLocal registry

Remote registryRemote registry

Virtual registryVirtual registry

Installing packages with dependencies from different sourcesInstalling packages with dependencies from different sources

See alsoSee also

Was the article helpful?

Installation from different registry types

Local registry

Remote registry

Virtual registry

Installing packages with dependencies from different sources

See also