Install & Compatibility
Where this runs
tested against v31.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.688s · 270.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 14.8s · import 1.326s · 269MB
278MB installed
● package 278MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GoogleAdsClient
✓ from google.ads.googleads.client import GoogleAdsClient
✗ import googleads
The `googleads` package is an old, deprecated library. The modern client for the Google Ads API is `google-ads`, imported via `google.ads.googleads`.
GoogleAdsException
✓ from google.ads.googleads.errors import GoogleAdsException
Initializes the Google Ads client and lists accessible customer IDs. Authentication is typically handled via a `google-ads.yaml` file in the user's home directory or through environment variables for sensitive credentials. Replace 'v16' with the latest stable API version.
import os
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
def main():
try:
# Authenticate using google-ads.yaml or environment variables
# For environment variables, set GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID,
# GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID.
# login_customer_id is required for some API calls, and should be the ID of the manager account.
client = GoogleAdsClient.load_from_storage(version='v16') # Use the latest API version
# Example: Get a list of accessible customer IDs
customer_service = client.get_service('CustomerService')
resource_names = customer_service.list_accessible_customers()
print('Accessible customer resource names:')
for resource_name in resource_names.resource_names:
print(f' - {resource_name}')
except GoogleAdsException as ex:
print(f'Request with ID "{ex.request_id}" failed with status "{ex.error.code().name}" and includes the following errors:')
for error in ex.errors:
print(f'\tError with message "{error.message}".')
if error.location:
for field_path_element in error.location.field_path_elements:
print(f'\t\tOn field: {field_path_element.field_name}')
except Exception as e:
print(f'An unexpected error occurred: {e}')
if __name__ == '__main__':
# Set environment variables for authentication if not using google-ads.yaml
# os.environ['GOOGLE_ADS_DEVELOPER_TOKEN'] = os.environ.get('GOOGLE_ADS_DEVELOPER_TOKEN', '')
# os.environ['GOOGLE_ADS_CLIENT_ID'] = os.environ.get('GOOGLE_ADS_CLIENT_ID', '')
# os.environ['GOOGLE_ADS_CLIENT_SECRET'] = os.environ.get('GOOGLE_ADS_CLIENT_SECRET', '')
# os.environ['GOOGLE_ADS_REFRESH_TOKEN'] = os.environ.get('GOOGLE_ADS_REFRESH_TOKEN', '')
# os.environ['GOOGLE_ADS_LOGIN_CUSTOMER_ID'] = os.environ.get('GOOGLE_ADS_LOGIN_CUSTOMER_ID', '') # Manager account ID
main()
google-ads --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.ads.google_ads' (or 'googleads')
The Python client library for the Google Ads API was installed, but the import path is incorrect, or an older, deprecated library ('googleads') is being referenced.
fixEnsure the `google-ads` library is installed (`pip install google-ads`) and use the correct import statement for the current library version: `from google.ads.googleads.client import GoogleAdsClient`.
AttributeError: '_Rendezvous' object has no attribute 'request_id'
This error occurs when attempting to access the `request_id` directly from the raw gRPC `_Rendezvous` object, which is returned in case of a gRPC error, rather than from a `GoogleAdsException` object.
fixWrap your Google Ads API calls in a `try...except google.ads.googleads.errors.GoogleAdsException as ex:` block. The `request_id` can then be accessed from `ex.request_id` within the exception handler.
google.auth.exceptions.RefreshError: invalid_grant (or AuthenticationError.NOT_ADS_USER, PERMISSION_DENIED)
These are common authentication and authorization issues. `invalid_grant` often means the refresh token is expired or revoked. `NOT_ADS_USER` or `PERMISSION_DENIED` indicates the Google account used for OAuth lacks necessary access to the Google Ads account, the client customer ID is incorrect, or required OAuth scopes are missing.
fixFor `invalid_grant`: Regenerate the OAuth2 refresh token, ensuring the Google Cloud project's OAuth consent screen publishing status is 'In production' if it's for long-term use, and revoke previous tokens before generating a new one. For `NOT_ADS_USER`/`PERMISSION_DENIED`: Verify the Google account used for authentication has active access to the Google Ads account, ensure the client customer ID is correct (e.g., '1234567890' not '123-456-7890'), and confirm that the OAuth scopes include `https://www.googleapis.com/auth/adwords`.
ValueError: Specified Google Ads API version 'vX' does not exist. Valid API versions are: 'vY', 'vZ'
The `GoogleAdsClient` was initialized with an API version string (`vX`) that is no longer supported or does not exist. The Google Ads API is updated quarterly, deprecating older versions.
fixUpdate the API version string used when initializing the client (e.g., `client.get_service('CampaignService', version='vX')`) to one of the currently valid versions listed in the error message or the latest official documentation. AttributeError: 'str' object has no attribute 'get' (when loading client config)
This error typically occurs when the `google-ads.yaml` configuration file is malformed, empty, or unreadable, causing the client loading method (`load_from_storage`, `load_from_string`, etc.) to return a string instead of a dictionary-like object that `get()` can be called on.
fixCarefully review the `google-ads.yaml` file for correct YAML syntax (indentation, key-value pairs), ensure all required fields are present, and verify the file path is correct and accessible. If loading from a string, ensure it's a valid YAML formatted string.
Upgrade
Version history
31.4.0latest on PyPI · released Aug 19, 2026
Audit
Dependencies
No dependency data recorded yet.