Store Python packages in Artifact Registry

This quickstart shows you how to set up a private Artifact Registry Python repository, upload a package, and then install the package.

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 Google Cloud project.

  4. Enable the Artifact Registry API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Artifact Registry API.

    Enable the API

Launch Cloud Shell

In this quickstart, you will use Cloud Shell, which is a shell environment for managing resources hosted on Google Cloud.

Cloud Shell comes preinstalled with the Google Cloud CLI and Python. The gcloud CLI provides the primary command-line interface for Google Cloud.

Launch Cloud Shell:

  1. Go to Google Cloud console.

    Google Cloud console

  2. On the Google Cloud console toolbar, click Activate Cloud Shell:

A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

Install required packages

Twine is a tool for publishing Python packages. You'll use Twine to upload a package to Artifact Registry.

In this quickstart, you use the Python installation included with Cloud Shell. This default installation includes the Artifact Registry keyring backend: to handle authentication with Artifact Registry. If you create a virtual environment or set up Python outside of Cloud Shell, you must install the keyring backend for authentication. For details, see Authenticating with keyring.

To install Twine, run the command:

pip install twine

You are now ready to set up Artifact Registry.

Create a repository

Create the repository for your packages.

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

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

    gcloud artifacts repositories list
  3. To simplify gcloud commands, set the default repository to quickstart-python-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-python-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 Artifact Registry keyring backend finds your credentials using Application Default Credentials (ADC), a strategy that looks for credentials in your environment.

In this quickstart, you'll:

  • Generate user credentials for ADC. In a production environment, you should use a service account and provide credentials with the GOOGLE_APPLICATION_CREDENTIALS environment variable.
  • Include the Artifact Registry repository URL in pip and twine commands so that you do not need to configure pip and Twine with the repository URL.

To generate credentials for ADC, run the following command:

gcloud auth application-default login

For details on authentication methods and adding repositories to pip and Twine configuration, see Setting up authentication to Python package repositories.

Obtain an example package

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

  1. Create a Python project folder named python-quickstart.

    mkdir python-quickstart
  2. Create a subdirectory named dist and then change to the directory.

    mkdir python-quickstart/dist
    cd python-quickstart/dist
  3. Download the sample Python packages that are used in the Python Packaging User Guide tutorial Packaging Python Projects.

    pip download sampleproject

    The command downloads the sampleproject package and its dependency, peppercorn.

Upload the package to the repository

Use Twine to upload your packages to your repository.

  1. From the dist directory, change to the parent python-quickstart directory.

    cd ..
  2. Upload the packages to the repository from your dist directory.

    python3 -m twine upload --repository-url dist/*

    When you run the command with python3 -m, Python locates twine and runs the command. If the twine command is in your system path, you can run it without python3 -m.

Twine uploads both sampleproject and peppercorn to your repository.

View the package in the repository

To verify that your package was added, list the packages in the quickstart-python-repo repository.

Run the following command:

gcloud artifacts packages list --repository=quickstart-python-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 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 flag to get more detailed output. See Troubleshooting for Python packages for more information.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, 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. To delete the quickstart-python-repo repository, run the following command:

    gcloud artifacts repositories delete quickstart-python-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