Google Cloud Compute Engine Client Library
raw JSON → 1.46.0 verified Tue May 12 auth: no python install: verified quickstart: verified
The `google-cloud-compute` Python client library provides programmatic access to Google Cloud Compute Engine, which delivers virtual machines running in Google's innovative data centers and worldwide fiber network. It allows developers to manage VM instances, disks, networks, and other Compute Engine resources. The library is actively maintained by Google and receives frequent updates, with the current version being 1.46.0.
pip install google-cloud-compute Common errors
error The caller does not have permission ↓
cause The user account or service account used for the operation lacks the necessary IAM permissions (roles) to perform the requested action on the Compute Engine resource or within the Google Cloud project.
fix
Grant the appropriate IAM role to the user or service account. For example, for creating VMs, grant
roles/compute.instanceAdmin.v1 or a broader role like roles/editor. Use gcloud projects add-iam-binding PROJECT_ID --member='user:ACCOUNT_EMAIL' --role='ROLES/COMPUTE.INSTANCEADMIN.V1' or manage permissions via the GCP Console. error The resource 'projects/PROJECT_ID' was not found. ↓
cause The specified project ID is incorrect, the project does not exist, or the user/service account does not have permission to view the project, making it appear as if it doesn't exist. Sometimes, it can also mean the Compute Engine API is not enabled for that project.
fix
Verify the project ID for correctness. Ensure the Compute Engine API is enabled for the project via the GCP Console or
gcloud services enable compute.googleapis.com. Confirm the authenticated account has at least roles/viewer on the project. error Compute Engine API has not been used in project PROJECT_NUMBER before or it is disabled. ↓
cause The Google Compute Engine API, which `google-cloud-compute` relies on, has not been activated or is currently disabled for the specified Google Cloud project.
fix
Enable the Compute Engine API for your project using the Google Cloud Console (APIs & Services -> Enabled APIs & services) or via the
gcloud CLI: gcloud services enable compute.googleapis.com --project=PROJECT_ID. error AttributeError: module 'collections' has no attribute 'Mapping' ↓
cause This error typically occurs when using the `gcloud` CLI (which some `google-cloud-compute` operations or authentication rely on) with Python 3.10 or newer. The `collections.Mapping` abstract base class was removed in Python 3.10 and moved to `collections.abc.Mapping`.
fix
Set the
CLOUDSDK_PYTHON environment variable to explicitly point to a compatible Python version (e.g., Python 3.9 or earlier) if you have one installed: export CLOUDSDK_PYTHON=/usr/bin/python3.9 (adjust path as needed). Alternatively, ensure your gcloud SDK is updated to a version that supports Python 3.10+. error The zone 'projects/PROJECT_ID/zones/ZONE_NAME' does not have enough resources available to fulfill the request. Try a different zone, or try again later. ↓
cause Google Cloud does not have sufficient capacity for the requested Compute Engine resource (e.g., VM instance, GPU) in the specified zone at that moment. This is common for popular machine types or specialized hardware like GPUs.
fix
Try creating the resource in a different zone. If the machine type is flexible, consider a different machine type or a custom machine type. You can also wait and retry the request at a later time, as resource availability can change. For persistent needs, request a quota increase.
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).
gotcha Operations requiring a Google Cloud project ID will fail if the `GCP_PROJECT_ID` environment variable is not set or if a placeholder project ID is used in the code. ↓
fix Ensure the `GCP_PROJECT_ID` environment variable is set to your actual Google Cloud project ID. Alternatively, pass the project ID explicitly as an argument to client methods where applicable.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 11.46s 122.9M
3.10 slim (glibc) - - 2.73s 121M
3.11 alpine (musl) - - 13.69s 135.7M
3.11 slim (glibc) - - 5.79s 133M
3.12 alpine (musl) - - 11.13s 126.0M
3.12 slim (glibc) - - 5.96s 124M
3.13 alpine (musl) - - 10.38s 124.4M
3.13 slim (glibc) - - 5.38s 122M
3.9 alpine (musl) - - 10.86s 124.1M
3.9 slim (glibc) - - 3.26s 122M
Imports
- InstancesClient wrong
from google.cloud.compute import Clientcorrectfrom google.cloud import compute_v1
Quickstart verified last tested: 2026-04-23
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.")