PyData Google Auth

1.9.1 verified Tue May 12 auth: no python install: verified

PyData Google Auth is a Python package that provides helper functions for authenticating to Google APIs, simplifying the process of obtaining and caching user and service account credentials. It wraps the underlying `google-auth` and `google-auth-oauthlib` libraries to offer a more convenient interface. The current version is 1.9.1, and the library maintains an active release cadence with frequent minor and patch updates.

pip install pydata-google-auth

Common errors

error ModuleNotFoundError: No module named 'pydata_google_auth' ↓

cause The `pydata-google-auth` package is not installed in the Python environment where the code is being executed, or the environment lacks access to the installed package.

fix

Install the package using pip: pip install pydata-google-auth or conda: conda install pydata-google-auth --channel conda-forge.

error google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. ↓

cause The application is attempting to use Google Application Default Credentials (ADC) but cannot find them in the expected locations, such as the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, a service account key file, or the Google Cloud metadata service (for GCE, Cloud Run, etc.).

fix

Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account key file (e.g., export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"), or run gcloud auth application-default login to set up user application default credentials locally.

error pydata_google_auth.exceptions.PyDataCredentialsError: Could not get any valid credentials. ↓

cause The `pydata-google-auth` library tried multiple methods (e.g., Application Default Credentials, cached user credentials, OAuth 2.0 flow) to obtain valid credentials but failed to retrieve any that were usable for the requested scopes.

fix

Ensure that a client_secrets.json file is correctly configured and accessible if using get_user_credentials, or that the environment variables for Application Default Credentials are set. Verify that the necessary API scopes are correctly provided and enabled for your Google Cloud project.

error google.auth.exceptions.RefreshError: The credentials do not contain the necessary fields need to refresh the access token. You must specify refresh_token, token_uri, client_id, and client_secret. ↓

cause The loaded credentials object is missing one or more required fields (e.g., `refresh_token`, `token_uri`, `client_id`, `client_secret`) that are essential for refreshing an expired access token, often occurring with manually constructed or incomplete credential objects.

fix

Ensure that when obtaining or loading user credentials, all necessary fields including refresh_token, token_uri, client_id, and client_secret are present in the google.oauth2.credentials.Credentials object. Re-run the full OAuth 2.0 authorization flow to acquire a complete set of credentials including a refresh token if these fields are missing.

error requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response')) ↓

cause A network-related issue, such as a firewall, proxy configuration, transient network problem, or an unresponsive server, prevented the HTTP request to Google's authentication or API servers from completing.

fix

Check your internet connection, verify proxy settings if applicable, inspect firewall rules to ensure outbound connections to Google's authentication endpoints (e.g., accounts.google.com) are allowed, and consider implementing retry logic for transient network failures.

Warnings

breaking The default behavior of `get_user_credentials` for `use_local_webserver` changed from `False` to `True` in version 1.4.0. This was due to Google's deprecation of the "out of band" (copy-paste token) OAuth flow. If you were explicitly setting `use_local_webserver=False` and relying on the console-based flow, this might break your application if you update without adjustment. ↓

fix Ensure your environment allows for a local web server (ports 8080-8089 by default) for the OAuth callback, or explicitly set `use_local_webserver=False` and be prepared for the console-based flow, which may eventually cease to function. The `auth_local_webserver` parameter is also deprecated; use `use_local_webserver` instead.

breaking Version 1.9.0 dropped support for Python versions older than 3.9. Projects on Python 3.8 or earlier will need to upgrade their Python interpreter to use this version or newer. ↓

fix Upgrade your Python environment to 3.9 or newer. Python 3.13 is now officially supported.

gotcha When developing a tool or library, you should provide your own `client_id` and `client_secret` when calling `get_user_credentials` to prevent masking your API client's identity, as per Google APIs terms of service. ↓

fix Obtain your own OAuth 2.0 Client ID and secret from the Google Cloud Console and pass them to the `client_id` and `client_secret` parameters of `get_user_credentials`.

gotcha For service account credentials, the JSON key file contains sensitive information. It is critical to manage this file securely, never commit it to source control, and use environment variables or secure storage mechanisms in production environments. ↓

fix Store the service account key in a secure location and reference its path via an environment variable (e.g., `GOOGLE_APPLICATION_CREDENTIALS`) or load it from a secure secret manager. Avoid hardcoding paths or embedding keys directly in code.

gotcha By default, `pydata-google-auth` caches user credentials on disk in `$HOME/.config/pydata/pydata_google_credentials.json` (or `$APPDATA` on Windows). On shared computing resources like Google Colab or GCE VMs, writing credentials to disk may be undesirable or insecure. ↓

fix To prevent credentials from being written to disk, pass `credentials_cache=pydata_google_auth.cache.NOOP` to `get_user_credentials` or `default`.

gotcha The `google.cloud` modules (e.g., `google.cloud.bigquery`) are not direct dependencies of `pydata-google-auth` and must be installed separately if you intend to use them. For example, to use BigQuery, you need to install `google-cloud-bigquery`. ↓

fix Install the specific `google.cloud` package you intend to use (e.g., `pip install google-cloud-bigquery`).

gotcha When using `pydata-google-auth` in conjunction with Google Cloud client libraries (e.g., `google-cloud-bigquery`, `google-cloud-storage`), ensure those client libraries are explicitly installed. `pydata-google-auth` provides authentication helpers but does not automatically install other `google-cloud` packages. ↓

fix Install the required Google Cloud client libraries (e.g., `pip install google-cloud-bigquery`) into your environment.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 1.26s 44.3M

3.10 alpine (musl) - - 1.16s 43.2M

3.10 slim (glibc) wheel 3.7s 0.91s 45M

3.10 slim (glibc) - - 0.93s 44M

3.11 alpine (musl) wheel - 1.55s 47.7M

3.11 alpine (musl) - - 1.66s 46.5M

3.11 slim (glibc) wheel 3.7s 1.32s 48M

3.11 slim (glibc) - - 1.27s 47M

3.12 alpine (musl) wheel - 1.59s 48.1M

3.12 alpine (musl) - - 1.67s 47.0M

3.12 slim (glibc) wheel 3.7s 1.60s 49M

3.12 slim (glibc) - - 1.63s 47M

3.13 alpine (musl) wheel - 1.62s 47.9M

3.13 alpine (musl) - - 1.63s 46.6M

3.13 slim (glibc) wheel 3.9s 1.57s 48M

3.13 slim (glibc) - - 1.64s 47M

3.9 alpine (musl) wheel - 1.16s 44.3M

3.9 alpine (musl) - - 1.08s 43.3M

3.9 slim (glibc) wheel 4.4s 1.03s 45M

3.9 slim (glibc) - - 0.94s 44M

Imports

get_user_credentials
```
from pydata_google_auth import get_user_credentials
```
Used for authenticating with user accounts via OAuth 2.0 flow.
load_service_account_credentials
```
from pydata_google_auth import load_service_account_credentials
```
Used for authenticating with service accounts using a JSON key file.
default
```
from pydata_google_auth import default
```
Attempts to get Application Default Credentials and falls back to user credentials if not found.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to obtain user credentials using `get_user_credentials` and then use them to initialize a Google Cloud BigQuery client. The process will typically open a browser window for you to authenticate via Google's OAuth 2.0 flow if credentials are not already cached.

import os
from pydata_google_auth import get_user_credentials
from google.cloud import bigquery

# Define the necessary scopes for BigQuery access
SCOPES = [
    'https://www.googleapis.com/auth/cloud-platform',
    'https://www.googleapis.com/auth/bigquery'
]

# Get user credentials (will open a browser for OAuth flow if not cached)
# `use_local_webserver=True` is the default and recommended for desktop apps.
credentials = get_user_credentials(SCOPES)

# Use an environment variable for project_id or replace with your actual ID
project_id = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id')

# Initialize a Google Cloud BigQuery client with the obtained credentials
client = bigquery.Client(project=project_id, credentials=credentials)

print(f"Authenticated successfully to project: {client.project}.")
print("You can now use 'client' to interact with BigQuery.")

# Example: List datasets (requires appropriate permissions for the scopes)
try:
    datasets = list(client.list_datasets())
    if datasets:
        print(f"Found {len(datasets)} datasets.")
    else:
        print("No datasets found in the project.")
except Exception as e:
    print(f"Error listing datasets: {e}")