Registry /
gcp / google-cloud-recommender
Install & Compatibility
Where this runs
tested against v2.21.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.910 runs
installs and imports cleanly · install 0.0s · import 1.945s · 69.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.5s · import 1.456s · 67MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RecommenderClient
✓ from google.cloud import recommender_v1
✗ from google.cloud import recommender_v1
This quickstart demonstrates how to initialize the `RecommenderClient` and list recommendations for a specific recommender (e.g., IAM policy recommendations) within a Google Cloud project. It uses environment variables for project ID, which is a best practice for authentication. Remember to enable the Recommender API and set up appropriate IAM permissions (e.g., `recommender.recommendations.list`).
import os
from google.cloud import recommender_v1
# Set your Google Cloud Project ID and a specific location
project_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id')
location = 'global' # Recommender often uses 'global' or a specific region
# Initialize the client
client = recommender_v1.RecommenderClient()
# Define the recommender name (e.g., for IAM policy recommendations)
# Common recommenders: google.iam.policy.Recommender, google.compute.instance.MachineTypeRecommender
recommender_name = f"projects/{project_id}/locations/{location}/recommenders/google.iam.policy.Recommender"
# List recommendations for a given recommender
try:
# Iterate through the paginated results
for recommendation in client.list_recommendations(parent=recommender_name):
print(f"Recommendation ID: {recommendation.name.split('/')[-1]}")
print(f"Description: {recommendation.description}")
print(f"State: {recommendation.state_info.state.name}")
if recommendation.primary_impact:
print(f"Primary Impact: {recommendation.primary_impact.category.name}")
print('---\n')
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure you have `recommender.recommendations.list` permission and `GCP_PROJECT_ID` is set correctly.")
Debug
Known issues
breakingOlder Python versions (e.g., 3.8 and below) are no longer supported. The library now requires Python 3.9 or newer. Ensure your development and deployment environments meet this requirement to avoid installation failures or runtime errors.fixUpgrade your Python environment to 3.9 or higher (e.g., `python3.9 -m pip install google-cloud-recommender`).
affects: <=2.0.0 (older versions), >=2.1.0 (requires >=3.9)
gotchaResource names for Google Cloud Recommender API calls (e.g., `parent`, `name`) must follow a strict, fully-qualified format (e.g., `projects/project-id/locations/location/recommenders/recommender-id`). Incorrect formatting will lead to `InvalidArgument` errors.fixAlways construct resource names carefully following the documentation's prescribed format, using f-strings or `RecommenderClient.common_location_path` helpers.
affects: All versions
gotchaThe Recommender API requires specific IAM permissions to list or get recommendations (e.g., `recommender.recommendations.list` for the target resource type). Lacking these permissions will result in a 403 Permission Denied error.fixEnsure the service account or user invoking the API has the necessary `roles/recommender.viewer` or custom roles with appropriate permissions granted at the project or resource level.
affects: All versions
gotchaThe `google-cloud-recommender` library provides both synchronous (`RecommenderClient`) and asynchronous (`RecommenderAsyncClient`) clients. Mixing methods or attempting to `await` on synchronous client calls will result in `TypeError` or unexpected behavior.fixUse `RecommenderClient` for blocking calls and `RecommenderAsyncClient` with `await` in an `async` context for non-blocking I/O. Do not interchange them without proper understanding.
affects: All versions
Upgrade
Version history
2.21.0latest on PyPI · released Mar 26, 2026
Audit
Dependencies
No dependency data recorded yet.