Stay organized with collections Save and categorize content based on your preferences.
This page describes how to configure authentication with an Artifact Registry Python package repository.
You must authenticate to Artifact Registry when you use a third-party application to connect to a repository.
You don't need to configure authentication for Cloud Build or Google Cloud runtime environments such as Google Kubernetes Engine and Cloud Run, but you should verify that the required permissions are configured.
Before you beginInstall the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update
.Artifact Registry supports the following authentication methods.
The instructions in this documentation describe configuring pip as the only package index that pip searches for packages. We recommend using virtual repositories to search packages across your private packages in Artifact Registry and public packages from PyPI instead of configuring multiple package indexes in the pip configuration file. The pip tool does not search package indexes in any particular order, so your consumers might mistakenly download or install a public package with the same name as one of your private packages. Virtual repositories let you configure priorities for upstream sources to mitigate this dependency confusion risk.
Authenticating with keyringThe 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.
Credential search orderWhen you use the Artifact Registry keyring backend, your credentials are not stored in your Python project. Instead, Artifact Registry searches for credentials in the following order:
Application Default Credentials (ADC), a strategy that looks for credentials in the following order:
Credentials defined in the GOOGLE_APPLICATION_CREDENTIALS
environment variable.
Credentials that the default service account for Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine, or Cloud Run functions provides.
Credentials provided by the Google Cloud CLI, including user credentials from the command gcloud auth application-default login
.
The GOOGLE_APPLICATION_CREDENTIALS
variable makes the account for authentication explicit, which makes troubleshooting easier. If you do not use the variable, verify that any accounts that ADC might use have the required permissions. For example the default service account for Compute Engine VMs, Google Kubernetes Engine nodes, and Cloud Run revisions has read-only access to repositories. If you intend to upload from these environments using the default service account, you must modify the permissions.
To set up authentication with the Artifact Registry keyring backend:
Install the keyring library.
pip install keyring
Install the Artifact Registry backend.
pip install keyrings.google-artifactregistry-auth
List backends to confirm the installation.
keyring --list-backends
The list should include
ChainerBackend(priority:10)
GooglePythonAuth(priority: 9)
Run the following command to print the repository configuration to add to your Python project.
gcloud artifacts print-settings python --project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION
Replace the following values:
Add the following settings to the .pypirc
file. The default location is:
$HOME/.pypirc
%USERPROFILE%\.pypirc
[distutils]
index-servers =
PYTHON-REPO-ID
[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
Replace the following values:
Add your repository to the pip configuration file. The file location depends on whether you want to update the per-user file or the file specific to a virtual environment that you are using.
For the file associated with your operating system user:
$HOME/.config/pip/pip.conf
or $HOME/.pip/pip.conf
/Library/Application Support/pip/pip.conf
or $HOME/.config/pip/pip.conf
%APPDATA%\pip\pip.ini
or %USERPROFILE%\pip\pip.ini
For virtual environments:
$VIRTUAL_ENV/pip.conf
%VIRTUAL_ENV%\pip.ini
To configure pip to only search your repository, use the index-url
setting and make sure there there are no other package indexes configured with the extra-index-url
setting.
[global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
The /simple/
string at the end of the repository path indicates that the repository implements the Python Simple Repository API.
Your Python environment is now configured to authenticate with Artifact Registry.
Keyring authentication with user credentialsAfter you have set up keyring, you can use keyring with your user credentials in the gcloud CLI. Sign in to Google Cloud CLI before connecting to a Python package repository.
Run the following command:
gcloud auth login
Note: Artifact Registry searches for credentials in a specific order. If service account credentials are found first, those credentials are used instead of your user credentials. Keyring authentication with service account credentials
After you have set up keyring, you can set up a service account for authentication.
Use one of the following options to authenticate with your service account:
Application Default Credentials (Recommended)
Assign the service account key file location to the variable GOOGLE_APPLICATION_CREDENTIALS
so that the Artifact Registry credential helper can obtain your key when connecting with repositories.
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
gcloud CLI credentials
Before connecting to a repository, sign in as the service account. Avoid this option if you are connecting to repositories from Compute Engine VMs since Artifact Registry finds the VM service account credentials before credentials in the gcloud CLI.
gcloud auth activate-service-account --key-file=KEY-FILE
Replace KEY-FILE with the path to the service account key file.
Use this approach when you require authentication with a username and password.
Service account keys are long-lived credentials. Use the following guidelines to limit access to your repositories:
To configure authentication:
Create a service account to act on behalf of your application, or choose an existing service account that you use for automation.
You will need the location of the service account key file to set up authentication with Artifact Registry. For existing accounts, you can view keys and create new keys on the Service Accounts page.
Go to the Service Accounts page
Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.If you acquired the service account key from an external source, you must validate it before use. For more information, see Security requirements for externally sourced credentials.
Grant the appropriate Artifact Registry role to the service account to provide repository access.
Run the following command to print the repository configuration to add to your Python project.
gcloud artifacts print-settings python --project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--json-key=KEY-FILE
Replace the following values:
Add the following settings to the .pypirc
file. The default location is for the per-user pip configuration file is:
$HOME/.pypirc
%USERPROFILE%\.pypirc
[distutils]
index-servers =
PYTHON-REPO-ID
[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY
Replace the following values:
Add your repository to the pip configuration file. The pip configuration file location depends on whether you want to update the per-user file or the file specific to a virtual environment that you are using.
For the file associated with your operating system user:
$HOME/.config/pip/pip.conf
or $HOME/.pip/pip.conf
/Library/Application Support/pip/pip.conf
or $HOME/.config/pip/pip.conf
%APPDATA%\pip\pip.ini
or %USERPROFILE%\pip\pip.ini
For virtual environments:
$VIRTUAL_ENV/pip.conf
%VIRTUAL_ENV%\pip.ini
Add the following line to the pip configuration file:
[global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
/simple/
string at the end of the repository path indicates that the repository implements the Python Simple Repository API.Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["This document provides instructions on how to configure authentication for connecting to an Artifact Registry Python package repository, specifically when using third-party applications."],["The recommended authentication method is using the Python keyring library, which utilizes Application Default Credentials (ADC) or credentials from the Google Cloud CLI, searching for credentials in a specific order."],["Alternatively, password authentication with a service account key is supported when the keyring library cannot be used, following best practices for managing service account credentials to ensure security."],["Users must install the keyring library and the Artifact Registry backend, as well as configure their `.pypirc` and pip configuration files with the repository details to complete the setup."],["The page also highlights the importance of utilizing virtual repositories to search packages across private and public sources, instead of configuring multiple package indexes in the pip configuration file to avoid dependency confusion."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4