Manage Python packages

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

Before you begin

1. Install and initialize the Google Cloud CLI.

   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.

Required roles

To get the permissions that you need to manage packages, ask your administrator to grant you the following IAM roles on the repository:

• View packages or files in packages: Artifact Registry Reader (roles/artifactregistry.reader)
• Download or install packages: Artifact Registry Reader (roles/artifactregistry.reader)
• Add packages to a repository: Artifact Registry Writer (roles/artifactregistry.writer)
• Delete packages: Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Adding packages

Repository modes: standard

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 a standard 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/*
   

Note: By default, Twine does not return detailed error messages. If you encounter an error, rerun the Twine command with the --verbose flag to get a more detailed message. See Troubleshooting for Python packages for information about some common error codes.

Viewing packages and versions

Repository modes: standard, remote

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.

For remote repositories, the returned list should include all direct and transitive dependencies.

Listing files

Repository modes: standard, remote

You can list files in a repository, files in all versions of a specified package, or files in a specific version of a 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: the regional or multi-regional location of the repository.
• PROJECT: your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
• REPOSITORY: the name of the repository where the image is stored.
• PACKAGE: the name of the package.
• VERSION: the version of the package.

Examples

Consider the following package information:

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

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

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

The following command lists files in version 1.0 of the package.

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

Installing packages

Repository modes: standard, remote, virtual

Use the pip command to install packages.

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

pip install PACKAGE

For standard repositories, you download a package directly from the repository.

For a remote repository, you download a cached copy of the package and its dependencies. If a cached copy does not exist, the remote repository downloads the package from the upstream source and caches it before serving it to you. You can verify that the remote repository retrieved the packages from the upstream source by viewing the list of packages in the repository.

For a virtual repository, Artifact Registry searches upstream repositories for the requested package.

• Upstream remote repositories will download and cache the requested package if a cached copy does not exist. Virtual repositories only serve requested packages, they do not store them.
• If you request a version that is available in more than one upstream repository, Artifact Registry chooses an upstream repository to use based on the priority settings configured for the virtual repository.

For example, consider a virtual repository with the following priority settings for upstream repositories:

• main-repo: Priority set to 100
• secondary-repo1: Priority set to 80.
• secondary-repo2: Priority set to 80.
• test-repo: Priority set to 20.

main-repo has the highest priority value, so the virtual repository always searches it first.

Both secondary-repo1 and secondary-repo2 have priority set to 80. If a requested package is not available in main-repo, Artifact Registry searches these repositories next. Since they both have the same priority value, Artifact Registry can choose to serve a package from either repository if the version is available in both of them.

test-repo has is lowest priority value and will serve a stored artifact if none of the other upstream repositories has it.

Additional information

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 are using a virtual repository, Artifact Registry uses the priorities configured in the upstream policy to choose a package when multiple upstream repositories have the requested package version. If two repositories with the package have the same priority, Artifact Registry serves it from either repository.
• If you configured pip 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.

You can override the index-url or extra-index-url settings in your requirements file. You can also use flags for these settings in your pip command. For example, this command overrides index-url with an Artifact Registry repository.

pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package

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

Note: By default, pip does not return detailed error messages. If you encounter an error, rerun the command with the -v or -vv flag to more detailed output. See Troubleshooting for Python packages for more information.

Deleting packages and versions

Repository modes: standard, remote

You can delete a package and all its versions, or delete a specific version.

• Once you delete a package, you cannot undo the action.
• For remote repositories, only the cached copy of the package is deleted. The upstream source is unaffected. If you delete a cached package, Artifact Registry will download and cache it again the next time the repository receives a request for the same package version.

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.

What's next

• Learn about managing Java packages
• Learn about managing Node.js packages
• Learn about managing container images
• Download individual files within a package