# 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

<br />

## Required roles


To get the permissions that
you need to create and manage Artifact Registry Python package repositories,

ask your administrator to grant you the
[Artifact Registry Administrator](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry#artifactregistry.admin) (`roles/artifactregistry.admin`) IAM role on your project.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Launch Cloud Shell

In this quickstart, you will use [Cloud Shell](https://docs.cloud.google.com/shell/docs),
which is a shell environment for managing resources hosted on
Google Cloud.

Cloud Shell comes preinstalled with the
[Google Cloud CLI](https://docs.cloud.google.com/sdk/gcloud)
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](https://console.cloud.google.com/)
2. On the Google Cloud console toolbar, click **Activate Cloud Shell** : ![](https://docs.cloud.google.com/static/artifact-registry/docs/images/cloud-shell.png)

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

## Install required packages

[Twine](https://pypi.org/project/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](https://pypi.org/project/keyrings.google-artifactregistry-auth):
to handle authentication with Artifact Registry. If you create
a [virtual environment](https://docs.python.org/3/tutorial/venv.html) or set up Python outside of
Cloud Shell, you must install the keyring backend for authentication.
For details, see [Authenticating with keyring](https://docs.cloud.google.com/artifact-registry/docs/python/authentication#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](https://docs.cloud.google.com/sdk/gcloud/reference/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](https://docs.cloud.google.com/artifact-registry/docs/python/authentication).

## 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](https://packaging.python.org/tutorials/packaging-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 https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/ 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 <var translate="no">PACKAGE</var> is the package ID.

## Install the package

Run the following command to install the package:

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

## Troubleshooting

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](https://docs.cloud.google.com/artifact-registry/docs/troubleshooting#pypi) 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

- [Learn more about configuring authentication](https://docs.cloud.google.com/artifact-registry/docs/python/authentication)
- [Learn about managing repositories](https://docs.cloud.google.com/artifact-registry/docs/repositories)
- [Learn about managing packages](https://docs.cloud.google.com/artifact-registry/docs/python/manage-packages)
- Read our resources about [DevOps](https://cloud.google.com/devops/) and explore our [research program](https://www.devops-research.com/research.html).