Google Cloud Compute Engine Client Library

Warnings

• breaking The `google-cloud-compute` library, along with other Google Cloud Python client libraries, has officially dropped support for Python 2.7 and Python 3.5.
  Fix: Upgrade your Python environment to Python 3.7 or newer. The library now supports Python >= 3.7, including 3.14.
• gotcha Relying on hardcoded API keys or service account key files for authentication in production environments is discouraged and a security risk.
  Fix: Leverage Application Default Credentials (ADC). For local development, use `gcloud auth application-default login`. For production on GCP, use service accounts attached to your compute resources (e.g., VMs, Cloud Run, Cloud Functions) which ADC will automatically pick up.
• gotcha Creating a new client instance (e.g., `compute_v1.InstancesClient()`) for every API call can lead to significant performance overhead due to connection establishment.
  Fix: Reuse a single client instance throughout your application's lifecycle, especially for frequent API interactions. Client libraries are designed to be long-lived and handle connection pooling internally.
• gotcha Many API list methods return paginated results. While Google Cloud client libraries automatically handle pagination using iterators, developers might incorrectly try to implement manual pagination, leading to inefficient code or missed results.
  Fix: Iterate directly over the results returned by list methods. The client library handles fetching subsequent pages transparently. If you need to access page-level metadata or stop iteration early, you can access the `.pages` attribute of the iterator.
• gotcha The library provides both synchronous and asynchronous clients (e.g., `InstancesClient` vs `InstancesAsyncClient`). Mixing synchronous and asynchronous patterns or choosing the wrong client for your workload (e.g., synchronous for high-concurrency I/O-bound tasks) can lead to performance bottlenecks.
  Fix: Choose either a synchronous or asynchronous client based on your application's architecture and stick to it. Asynchronous clients are generally preferred for I/O-bound operations and high concurrency (e.g., web servers, batch processing), while synchronous clients are simpler for sequential scripts.
• gotcha Due to the large size of `google-cloud-compute` and other Google Cloud Python libraries, code completion in JetBrains IDEs (like PyCharm) may fail.
  Fix: Increase the `idea.max.intellisense.filesize` setting in your IDE's custom properties (Help -> Edit custom properties…) to a larger value, such as `10000` (10MB).

Install

• pip install google-cloud-compute Install stable version

Imports

• InstancesClient

  from google.cloud import compute_v1

  The canonical import path for Compute Engine v1 API client is `google.cloud.compute_v1`. Older or incorrect patterns might refer to `google.cloud.compute` directly, which is not the recommended or stable way to access the specific API version.

Quickstart

This quickstart code demonstrates how to authenticate and list all virtual machine instances within a specified Google Cloud project. It uses Application Default Credentials (ADC) for authentication, which is the recommended method. Replace `your-gcp-project-id` or set the `GCP_PROJECT_ID` environment variable.

import google.cloud.compute_v1 as compute_v1
import os

def list_all_instances(project_id: str) -> None:
    """Lists all instances across all zones in the given project."""
    client = compute_v1.InstancesClient()
    # aggregated_list returns instances grouped by zone
    aggregated_list = client.aggregated_list(project=project_id)

    print(f"Instances in project {project_id}:")
    for zone, scope in aggregated_list.items():
        if scope.instances:
            print(f"  Zone: {zone}")
            for instance in scope.instances:
                print(f"    - {instance.name} ({instance.status})")

# Replace with your Google Cloud Project ID or set as an environment variable
PROJECT_ID = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id')

if PROJECT_ID == 'your-gcp-project-id':
    print("WARNING: Please set the 'GCP_PROJECT_ID' environment variable or replace 'your-gcp-project-id' in the code.")
else:
    try:
        list_all_instances(PROJECT_ID)
    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure the Compute Engine API is enabled for your project and your credentials are set up correctly.")