Google Cloud Run Client Library
raw JSON → 0.16.0 verified Tue May 12 auth: no python install: verified quickstart: verified
The `google-cloud-run` Python library is the official client library for interacting with the Google Cloud Run Admin API. It enables developers to programmatically manage Cloud Run services and jobs, including deployment, configuration, and monitoring. Currently at version 0.16.0, this library is part of the larger `google-cloud-python` monorepo and receives frequent updates, typically with a release cadence aligning with other Google Cloud client libraries.
pip install google-cloud-run Common errors
error Revision REVISION_NAME is not ready and cannot serve traffic. The user provided container failed to start and listen on port defined by PORT=8080 environment variable ↓
cause The Python application inside your container is not listening on the port specified by the PORT environment variable (which defaults to 8080 on Cloud Run), or it encountered a critical error during startup that prevented it from becoming ready to serve requests.
fix
Ensure your Python application binds to all network interfaces (
0.0.0.0) and the port specified by the PORT environment variable. For example, using a common web framework like Flask: app.run(host='0.0.0.0', port=int(os.environ.get('PORT', 8080))). Check your application logs for specific startup errors. error ModuleNotFoundError: No module named 'google.cloud' ↓
cause This error indicates that the `google-cloud-run` library or one of its core `google.cloud` dependencies is not correctly installed within your container image or the Python environment where your code is executing on Cloud Run.
fix
Add
google-cloud-run (and any other necessary google-cloud libraries) to your requirements.txt file and ensure that pip install -r requirements.txt is run during your Docker image build process or by the Cloud Run buildpacks if deploying from source. error PERMISSION_DENIED: User must have permission to read the image ↓
cause The service account or user attempting to deploy the Cloud Run service lacks the necessary Identity and Access Management (IAM) permissions to access the container image stored in Artifact Registry or Container Registry, or to perform other required deployment actions.
fix
Grant the appropriate IAM roles to the deploying identity or the Cloud Run service agent. This often includes
roles/storage.objectViewer for accessing the image, and roles/run.admin or roles/run.developer for managing Cloud Run services, on the respective project or repository. error AttributeError: module 'collections' has no attribute 'Mapping' ↓
cause This specific error occurs when the `gcloud` SDK, which uses Python internally, encounters a compatibility issue with its internal dependencies or your system's Python version (typically Python 3.10 or newer) where `collections.Mapping` has been moved or removed.
fix
Update your Google Cloud SDK components by running
gcloud components update. If the issue persists, consider ensuring gcloud uses a compatible Python version, potentially by setting a specific Python executable in your environment or reinstalling the SDK. error ERROR: failed to launch: direct exec: no such file or directory ↓
cause When running a Cloud Run Job, the executable command or script specified as the entry point in your container image (or in the job configuration) cannot be found or is incorrectly configured, which often happens when adapting a service container for a job.
fix
Verify the
ENTRYPOINT or CMD instruction in your Dockerfile, or the --command and --args parameters in your gcloud run jobs deploy command, to ensure they point to a valid, executable file within the container and provide the correct arguments for a standalone job execution. Warnings
gotcha The `google-cloud-run` library primarily targets the Cloud Run Admin API v2. Ensure you are using the correct client for the API version you intend to interact with, as API object structures and methods may differ significantly between v1 and v2, potentially leading to `TypeError` or unexpected behavior. ↓
fix Consult the official client library documentation (e.g., `google.cloud.run_v2`) and the Cloud Run Admin API documentation to confirm the correct API version and client methods for your use case.
gotcha When constructing resource names for services or jobs (e.g., in `get_service` or `create_service` calls), ensure they follow the expected format: `projects/{project_id}/locations/{location}/services/{service_id}`. Incorrect formatting can result in `NotFound` or `InvalidArgument` errors. ↓
fix Always use f-strings or `.format()` to construct resource names dynamically, ensuring all path components (project ID, location, service ID) are correctly included and ordered. For example, `parent = f"projects/{project_id}/locations/{location}"`.
gotcha The library uses standard Python logging, but by default, logging events are not handled, and logs may contain sensitive information. For visibility and security, you must explicitly configure logging or set the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable. ↓
fix To enable default logging, set the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to `google` or `google.cloud.run_v2`. For advanced configuration, use Python's `logging` module to set up handlers and formatters, e.g., `logging.basicConfig(level=logging.INFO)`.
gotcha Using the client library to manage Cloud Run resources requires appropriate IAM permissions on the Google Cloud project and specific resources. Lack of permissions will result in `PermissionDenied` errors. ↓
fix Grant the service account or user credentials used by your application the necessary IAM roles, such as 'Cloud Run Admin' (`roles/run.admin`) or more granular roles like 'Cloud Run Developer' (`roles/run.developer`) for deployment, or 'Cloud Run Viewer' (`roles/run.viewer`) for read-only access.
gotcha Operations with the client library often require a Google Cloud project ID. If not explicitly provided in client constructors or method calls, the library attempts to infer it from environment variables (e.g., `GOOGLE_CLOUD_PROJECT`, `GCP_PROJECT`, `PROJECT_ID`, or `GOOGLE_CLOUD_PROJECT_ID`) or application default credentials. Failing to provide a valid project ID will prevent resource lookup or creation, leading to errors like `NotFound`, `InvalidArgument`, or specific error messages prompting you to set the project ID. ↓
fix Ensure the Google Cloud Project ID is accessible to the client library. The most common methods are: 1. Setting the `GOOGLE_CLOUD_PROJECT` environment variable (or other recognized variables like `GOOGLE_CLOUD_PROJECT_ID`). 2. Explicitly passing `project='your-project-id'` to the client constructor (e.g., `run_v2.ServicesClient(project='your-project-id')`) or relevant method calls.
gotcha The Cloud Run client library requires a Google Cloud project ID to identify the target project. This is often provided via the `GOOGLE_CLOUD_PROJECT_ID` environment variable or directly in API calls. Not providing it will result in errors indicating a missing project identifier or invalid resource names. ↓
fix Set the `GOOGLE_CLOUD_PROJECT_ID` environment variable (or `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`) before running your application, or ensure the project ID is explicitly passed to relevant client methods or during client initialization.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 2.13s 72.6M
3.10 alpine (musl) - - 2.12s 71.5M
3.10 slim (glibc) wheel 6.1s 1.13s 70M
3.10 slim (glibc) - - 1.13s 69M
3.11 alpine (musl) wheel - 2.70s 77.8M
3.11 alpine (musl) - - 3.06s 76.7M
3.11 slim (glibc) wheel 5.3s 1.75s 76M
3.11 slim (glibc) - - 1.70s 74M
3.12 alpine (musl) wheel - 2.79s 69.2M
3.12 alpine (musl) - - 2.95s 68.1M
3.12 slim (glibc) wheel 4.4s 1.94s 67M
3.12 slim (glibc) - - 2.30s 66M
3.13 alpine (musl) wheel - 2.61s 68.8M
3.13 alpine (musl) - - 3.00s 67.6M
3.13 slim (glibc) wheel 4.9s 1.94s 67M
3.13 slim (glibc) - - 2.34s 65M
3.9 alpine (musl) wheel - 1.92s 72.7M
3.9 alpine (musl) - - 1.91s 71.6M
3.9 slim (glibc) wheel 7.0s 1.36s 70M
3.9 slim (glibc) - - 1.20s 69M
Imports
- ServicesClient
from google.cloud.run_v2 import ServicesClient - JobsClient
from google.cloud.run_v2 import JobsClient
Quickstart verified last tested: 2026-04-24
import os
from google.cloud.run_v2 import ServicesClient
def list_cloud_run_services(project_id: str, location: str):
"""Lists Cloud Run services in a given project and location."""
client = ServicesClient()
parent = f"projects/{project_id}/locations/{location}"
try:
# Paged iteration over services
print(f"Fetching services for parent: {parent}")
for service in client.list_services(parent=parent):
print(f"Service Name: {service.name}")
print(f" URI: {service.uri}")
# You can access more service attributes here, e.g., service.traffic
print("-" * 20)
except Exception as e:
print(f"Error listing services: {e}")
if __name__ == "__main__":
# Set your Google Cloud Project ID and desired location
# Ensure GOOGLE_APPLICATION_CREDENTIALS is set or you are running in a GCP environment
# e.g., 'export GOOGLE_CLOUD_PROJECT_ID="your-project"'
# e.g., 'export GOOGLE_CLOUD_LOCATION="us-central1"'
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT_ID", "your-project-id")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
if project_id == "your-project-id":
print("Please set the GOOGLE_CLOUD_PROJECT_ID environment variable or replace 'your-project-id' in the script.")
else:
list_cloud_run_services(project_id, location)