Manage Python packages

Stay organized with collections Save and categorize content based on your preferences.

This page describes adding, viewing, and deleting Python packages and package versions.

Before you begin

  1. Verify that you have enabled the Artifact Registry API and installed Google Cloud CLI. See Enabling and disabling service for instructions.

    Google Cloud CLI version 354.0.0 or newer is required to run commands for Python repositories. You can check the version with the command:

    gcloud version
    
  2. If the target repository does not exist, create a new Python package repository.

  3. Verify that Python 3 is installed. For installation instructions, see the Google Cloud tutorial for setting up Python.

  4. (Optional) Configure defaults for gcloud commands.

  5. If you are using keyring authentication with gcloud credentials, log in to Google Cloud CLI with your user account or service account.

Adding packages

Required permissions: Artifact Registry Writer

When you build a Python project, distribution files are saved in a dist subdirectory in your project. You can then use Twine to upload packages to the repository.

We recommend the following best practices for your packages:

  • Use unique names for your private packages so that they do not match package names on pypi.org, particularly if your pip configuration includes multiple package indexes.
  • Use the version identifier specification in PEP 440 for your package version numbers. By default, pip only installs stable releases. It uses the version identifier specification to distinguish stable versions from pre-release versions and to parse any requirements for the version to install.

To add a package:

  1. Install Twine.

    pip install twine
    
  2. Change to your Python project directory.

  3. Upload the distribution files to the repository from the project dist subdirectory. Run the following command:

    twine upload dist/*
    

    You can specify a particular repository with the --repository-url flag.

    twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
    

Viewing packages and versions

Required permissions: Artifact Registry Reader

To view packages and package versions using the Google Cloud console or gcloud:

Console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Click a package to view versions of the package.

gcloud

To list packages in a repository, run the following command:

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

Where

  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

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

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Where

  • PACKAGE is the ID of the package or fully qualified identifier for the package.
  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

Listing files

You can list files in a repository, files in all versions of a specified container package, or files in a specific version of an package.

For all the following commands, you can set a maximum number of files to return by adding the --limit flag to the command.

To list all files in the default project, repository, and location when the default values are configured:

gcloud artifacts files list

To list files in a specified project, repository, and location, run the command:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

To list files for all versions of a specific package:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

To list files for a specific package version:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

Replace the following values:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY is the name of the repository where the image is stored.
  • PACKAGE is the name of the package.
  • VERSION is the version of the package.

Examples

Consider the following package information:

  • Project: my-project
  • Repository: my-repo
  • Repository location: us-central1
  • Package: my-app

The following command lists all files in the repository my-repo in the location us-central1 within the default project:

gcloud artifacts files list
    --location=us-central1 \
    --repository=my-repo
The following command lists files in version 1.0 of the package.

gcloud artifacts files list
    --project=my-project \
    --location=us-central1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

Deleting packages and versions

Required permissions: Artifact Registry Repository Administrator

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Select the package that you want to delete.

  4. Click DELETE.

  5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Where

  • PACKAGE is the name of the package in the repository.
  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
  • --async Return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Click a package to view versions of that package.

  4. Select versions that you want to delete.

  5. Click DELETE.

  6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Where

  • PACKAGE is the name of the package in the repository.
  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
  • --async returns immediately, without waiting for the operation in progress to complete.

Installing packages

Required permissions: Artifact Registry Reader

Use the pip command to install packages from the repository.

To install the latest stable release of a package, run the command:

pip install PACKAGE

By default, pip installs stable versions of a package and ignores pre-release versions. PEP 440 defines the Python version identifier specification that pip users to parse version numbers, including pre-release versions.

To include pre-release versions when pip searches for a package to install, the --pre flag to your command.

pip install --pre PACKAGE

To specify a required version or version range, include a requirement specifier. You can include the version requirement directly in your command or use a requirements file.

For example, this command specifies that the minimum version of my-package is development version 1.0.dev0.

pip install --pre my-package>=1.0.dev0

Stable releases are considered newer than pre-releases, so if version 1.0 is in the repository, pip will choose version 1.0 over a pre-release version.

If you do not specify a repository, your pip configuration in pip.conf determines how pip searches for the package.

  • If you configured the Artifact Registry repository with the index-url setting and no other package indexes are configured, pip only searches your Artifact Registry repository for the package.
  • If you configured the repository with the extra-index-url setting or if you configured multiple package indexes, pip searches pypi.org and any other configured package indexes and chooses the latest version of the package.

Alternatively, you can specify the repository to search by adding the --index-url flag to the command.

pip install --index-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/ PACKAGE

For more information about installing packages, see the Python Packaging documentation.

What's next