Quickstart for Python

This quickstart shows you how to set up an Artifact Registry PyPI repository and upload a package to it.

Package management is in alpha. It is only available to alpha users, and might not include all features available for container management. To apply for the alpha, complete the sign up form. For more information, see Requirements to access alpha features.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the Artifact Registry API.

    Enable the API

  5. Version 329.0.0 of the gcloud tool is required to work with PyPI repositories. Install and initialize Cloud SDK if it is not already installed. For an existing installation, update components with the command:

        gcloud components update

    You can check the gcloud tool version with the command:

        gcloud version
  6. Install Python 3 and create a Python virtual environment. For instructions for these steps, see the Google Cloud tutorial for setting up Python.

Create a repository

Create the repository for your packages.

  1. Create the repository:


    1. Open the Repositories page in the Cloud Console.

      Open the Repositories page

    2. Click Create Repository.

    3. Specify quickstart-pypi-repo as the repository name.

    4. Choose PyPI as the format.

    5. Under Location Type, select Region and then choose the location us-central1.

    6. Click Create.

    The repository is added to the repository list.


    1. Run the following command to create a new PyPI repository in the current project named quickstart-pypi-repo in the location us-central1.

      gcloud alpha artifacts repositories create quickstart-pypi-repo \
          --repository-format=pypi \
          --location=us-central1 \
          --description="PyPI repository"
    2. Run the following command to verify that your repository was created:

      gcloud artifacts repositories list

    For more information about Artifact Registry commands, run the command gcloud artifacts.

  2. To simplify gcloud commands, set the default repository to quickstart-pypi-repo and the default location to us-central1. After the values are set, you do not need to specify them in gcloud commands that require a repository or a location.

    To set the repository, run the command:

    gcloud config set artifacts/repository quickstart-pypi-repo

    To set the location, run the command:

    gcloud config set artifacts/location us-central1

    For more information about these commands, see the gcloud config set documentation.

Configure authentication

The Python keyring library provides applications with a way to access keyring backends, meaning operating system and third-party credential stores.

Artifact Registry provides the keyrings.google-artifactregistry-auth keyring backend to handle authentication with Artifact Registry repositories. When you use this backend, Artifact Registry automatically finds your credentials in the environment.

To set up authentication with the Artifact Registry keyring backend:

  1. In pip version 21.1, the behavior for querying keyring for credentials changed. To ensure that you are using a version of pip that can authenticate with Artifact Registry repositories:

    1. Check your version of pip.

      pip --version
    2. If you are using version 21.1 or newer, install version 21.01 instead.

      python -m pip install pip==21.01
  2. Install the keyring library.

    pip install keyring
  3. Install the Artifact Registry backend.

    pip install keyrings.google-artifactregistry-auth
  4. List backends to confirm the installation.

    keyring --list-backends

    The list should include

    • ChainerBackend(priority:10)
    • GooglePyPIAuth(priority: 9)
  5. Run the following command to print the repository configuration to add to your Python project.

    gcloud alpha artifacts print-settings pypi

    The output looks similar to the following example:

    # Insert the following snippet into your .pypirc
    index-servers =
    repository: https://us-central1-pypi.pkg.dev/PROJECT/quickstart-pypi-repo/
    # Insert the following snippet into your pip.conf
    index-url = https://us-central1-pypi.pkg.dev/PROJECT/quickstart-pypi-repo/simple/
  6. Add the following settings to the .pypirc file. The default location is for the per-user pip configuration file is:

    • Linux and MacOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    index-servers =
    repository: https://us-central1-pypi.pkg.dev/PROJECT/quickstart-pypi-repo/

    Replace PROJECT with your project ID.

  7. Edit the pip configuration file to include the following setting in the [global] section. The default location is for the per-user pip configuration file is:

    • Linux: $HOME/.config/pip/pip.conf or $HOME/.pip/pip.conf
    • MacOS: /Library/Application Support/pip/pip.conf or $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini or %USERPROFILE%\pip\pip.ini

    For this quickstart, configure pip to only search the Artifact Registry repository. Add the following setting to the [global] section:

    index-url = https://us-central1-pypi.pkg.dev/PROJECT/quickstart-pypi-repo/simple/

    The /simple/ string at the end of the repository path indicates that the repository implements the Python Simple Repository API.

  8. Log in to Cloud SDK with your user credentials.

    gcloud auth login

Your Python environment is now configured to authenticate with Artifact Registry.

Obtain an example package

When you build a Python project, packages are saved in a dist subdirectory in your Python project. To simplify this quickstart, you will download prebuilt package files.

  1. Create a directory named dist and then change to the directory.

    mkdir dist
    cd dist
  2. Download the sample Python packages. This sample project is used in the Python Packaging User Guide tutorial Packaging Python Projects.

    Newer versions of pip use the Wheel file for installation (the file ending in .whl). If needed, pip falls back to the tar file for installation.

Upload the package to the repository

Use the Python tool Twine to publish packages.

  1. Install Twine.

    pip install twine
  2. Upload the packages to the repository from your dist directory.

    twine upload --repository-url https://us-central1-pypi.pkg.dev/PROJECT/quickstart-pypi-repo/ dist/*

View the package in the repository

To verify that your package was added to the repository:


  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. In the repository list, click the quickstart-pypi-repo repository.

    The Packages page lists the packages in the repository.


To list the packages in the quickstart-pypi-repo repository, run the following command:

gcloud artifacts packages list --repository=quickstart-pypi-repo

To view versions for a package, run the following command:

gcloud artifacts versions list --package=PACKAGE

Where PACKAGE is the package ID.

Install the package

Run the following command to install the package:

pip install --index-url https://us-central1-pypi.pkg.dev/PROJECT/quickstart-pypi-repo/simple/ sampleproject


By default, tools such as pip and Twine do not return detailed error messages. If you encounter an error, rerun the command with the --verbose parameter to get a more detailed message. See Troubleshooting for an example.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, follow these steps.

Before you remove the repository, ensure that any packages you want to keep are available in another location.

To delete the repository:


  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. In the repository list, select the quickstart-pypi-repo repository.

  3. Click Delete.


  1. To delete the quickstart-pypi-repo repository, run the following command:

    gcloud artifacts repositories delete quickstart-pypi-repo
  2. If you want to remove the default repository and location settings that you configured for the active gcloud configuration, run the following commands:

    gcloud config unset artifacts/repository
    gcloud config unset artifacts/location

What's next