{"id":766,"library":"google-cloud-run","title":"Google Cloud Run Client Library","description":"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.","status":"active","version":"0.16.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-run","tags":["google cloud","serverless","cloud run","api client","gcp"],"install":[{"cmd":"pip install google-cloud-run","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library for Google API clients","package":"google-api-core"},{"reason":"Handles authentication with Google Cloud","package":"google-auth"},{"reason":"Protocol buffers for API communication","package":"google-protobuf"},{"reason":"Common protocol buffer definitions for Google APIs","package":"googleapis-common-protos"}],"imports":[{"symbol":"ServicesClient","correct":"from google.cloud.run_v2 import ServicesClient"},{"symbol":"JobsClient","correct":"from google.cloud.run_v2 import JobsClient"}],"quickstart":{"code":"import os\nfrom google.cloud.run_v2 import ServicesClient\n\ndef list_cloud_run_services(project_id: str, location: str):\n    \"\"\"Lists Cloud Run services in a given project and location.\"\"\"\n    client = ServicesClient()\n    parent = f\"projects/{project_id}/locations/{location}\"\n\n    try:\n        # Paged iteration over services\n        print(f\"Fetching services for parent: {parent}\")\n        for service in client.list_services(parent=parent):\n            print(f\"Service Name: {service.name}\")\n            print(f\"  URI: {service.uri}\")\n            # You can access more service attributes here, e.g., service.traffic\n            print(\"-\" * 20)\n    except Exception as e:\n        print(f\"Error listing services: {e}\")\n\nif __name__ == \"__main__\":\n    # Set your Google Cloud Project ID and desired location\n    # Ensure GOOGLE_APPLICATION_CREDENTIALS is set or you are running in a GCP environment\n    # e.g., 'export GOOGLE_CLOUD_PROJECT_ID=\"your-project\"'\n    # e.g., 'export GOOGLE_CLOUD_LOCATION=\"us-central1\"'\n    project_id = os.environ.get(\"GOOGLE_CLOUD_PROJECT_ID\", \"your-project-id\")\n    location = os.environ.get(\"GOOGLE_CLOUD_LOCATION\", \"us-central1\")\n\n    if project_id == \"your-project-id\":\n        print(\"Please set the GOOGLE_CLOUD_PROJECT_ID environment variable or replace 'your-project-id' in the script.\")\n    else:\n        list_cloud_run_services(project_id, location)\n","lang":"python","description":"This quickstart demonstrates how to instantiate the `ServicesClient` and list existing Cloud Run services within a specified Google Cloud project and location. Ensure your environment is authenticated (e.g., via `gcloud auth application-default login` or by setting `GOOGLE_APPLICATION_CREDENTIALS`) and that `GOOGLE_CLOUD_PROJECT_ID` and `GOOGLE_CLOUD_LOCATION` environment variables are set."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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}\"`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:48:26.965Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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.","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.","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"},{"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.","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.","error":"ModuleNotFoundError: No module named 'google.cloud'"},{"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.","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.","error":"PERMISSION_DENIED: User must have permission to read the image"},{"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.","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.","error":"AttributeError: module 'collections' has no attribute 'Mapping'"},{"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.","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.","error":"ERROR: failed to launch: direct exec: no such file or directory"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"0.16.0","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.13,"mem_mb":31.9,"disk_size":"72.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.12,"mem_mb":32.1,"disk_size":"71.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.1,"import_time_s":1.13,"mem_mb":25,"disk_size":"70M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":25.2,"disk_size":"69M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.7,"mem_mb":33.9,"disk_size":"77.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.06,"mem_mb":34.1,"disk_size":"76.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.3,"import_time_s":1.75,"mem_mb":27.6,"disk_size":"76M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.7,"mem_mb":27.9,"disk_size":"74M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.79,"mem_mb":33.5,"disk_size":"69.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.95,"mem_mb":33.8,"disk_size":"68.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.4,"import_time_s":1.94,"mem_mb":27.3,"disk_size":"67M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.3,"mem_mb":27.6,"disk_size":"66M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.61,"mem_mb":34,"disk_size":"68.8M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3,"mem_mb":34.5,"disk_size":"67.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.9,"import_time_s":1.94,"mem_mb":27.7,"disk_size":"67M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.34,"mem_mb":28.2,"disk_size":"65M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.92,"mem_mb":31.9,"disk_size":"72.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.91,"mem_mb":31.7,"disk_size":"71.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7,"import_time_s":1.36,"mem_mb":25,"disk_size":"70M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.2,"mem_mb":24.8,"disk_size":"69M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}