{"id":8203,"library":"google-compute-engine","title":"Google Compute Engine Guest Environment Utilities","description":"The `google-compute-engine` library provides core utilities, scripts, and daemons that run within Google Compute Engine (GCE) virtual machine instances. It enables VMs to properly interact with the GCE platform, primarily by reading from and writing to the metadata server. This package is part of the standard Google-provided OS images for Compute Engine, and its primary role is to facilitate the VM's lifecycle and configuration, rather than acting as a client library for managing GCE resources externally. The latest PyPI version is 2.8.13, but the public releases on GitHub are quite old (late 2019), indicating an infrequent, system-level release cadence.","status":"active","version":"2.8.13","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/compute-image-packages","tags":["google cloud","compute engine","vm","metadata","guest environment"],"install":[{"cmd":"pip install google-compute-engine","lang":"bash","label":"Install via pip (on a GCE VM)"}],"dependencies":[],"imports":[{"note":"The `google-compute-engine` package is for internal VM utilities, not a general-purpose Python client for the Compute Engine API. For API interaction, use `google-cloud-compute`.","wrong":"from google_compute_engine import ComputeEngineClient","symbol":"metadata_server","correct":"import requests\n# This library's components are primarily system-level agents,\n# not typically imported directly by user applications for API access.\n# Interaction on a GCE VM is usually via the metadata server."}],"quickstart":{"code":"import requests\nimport json\nimport os\n\n# This quickstart demonstrates how to access VM metadata from within a Google Compute Engine instance.\n# The google-compute-engine package helps manage this interaction at a system level.\n\nMETADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/'\nHEADERS = {'Metadata-Flavor': 'Google'}\n\ndef get_metadata(path):\n    try:\n        response = requests.get(METADATA_URL + path, headers=HEADERS, timeout=1)\n        response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)\n        return response.text\n    except requests.exceptions.RequestException as e:\n        # Check if running on a GCE instance or if URL is accessible\n        if 'metadata.google.internal' in str(e):\n            return f\"Error accessing metadata. This code must run inside a Google Compute Engine VM. Details: {e}\"\n        else:\n            return f\"Error accessing metadata: {e}\"\n\nif __name__ == '__main__':\n    print('--- Instance Name ---')\n    instance_name = get_metadata('instance/name')\n    print(f'Instance Name: {instance_name}')\n\n    print('\\n--- Project ID ---')\n    project_id = get_metadata('project/project-id')\n    print(f'Project ID: {project_id}')\n\n    print('\\n--- Zone ---')\n    zone_full = get_metadata('instance/zone')\n    zone = zone_full.split('/')[-1] if 'zones/' in zone_full else zone_full\n    print(f'Zone: {zone}')\n\n    print('\\n--- Custom Metadata (example) ---')\n    # To test custom metadata, add a key-value pair 'my-custom-key: my-custom-value'\n    # to your VM or project metadata via gcloud CLI or Cloud Console.\n    # Example: gcloud compute instances add-metadata my-instance --metadata=my-custom-key=my-custom-value --zone=us-central1-a\n    custom_key = 'instance/attributes/my-custom-key'\n    custom_value = get_metadata(custom_key)\n    print(f'Custom Metadata (my-custom-key): {custom_value}')\n\n    print('\\n--- All Project Attributes (JSON format) ---')\n    all_project_attributes_json = get_metadata('project/attributes/?recursive=true')\n    try:\n        print(json.dumps(json.loads(all_project_attributes_json), indent=2))\n    except json.JSONDecodeError:\n        print(all_project_attributes_json)\n\n","lang":"python","description":"This quickstart demonstrates how to programmatically retrieve VM and project metadata from within a Google Compute Engine instance using Python's `requests` library. This is the primary way applications and system scripts on a GCE VM interact with the environment, often leveraged by the underlying `google-compute-engine` guest environment components. The metadata server provides crucial information like instance name, project ID, zone, and custom metadata, which are essential for applications to adapt to their running environment. This code should be run directly on a GCE VM."},"warnings":[{"fix":"For managing Google Compute Engine resources (e.g., creating VMs, disks, networks) from application code, use `pip install google-cloud-compute` and import `from google.cloud import compute_v1`. Do not attempt to use `google-compute-engine` for this purpose.","message":"This library (`google-compute-engine`) is distinct from the Google Cloud Client Library for Compute Engine (`google-cloud-compute`). This package provides low-level guest environment utilities for VMs, while `google-cloud-compute` is the idiomatic Python client to interact with the Compute Engine API for managing resources from an external application.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For new application development involving Google Compute Engine, prioritize the use of `google-cloud-compute` which is actively maintained and provides current API access.","message":"The public GitHub releases for `google-compute-engine` have not been updated since late 2019 (v20191210). While the package remains functional and is included in GCE images, significant active development or new Python-facing features should not be expected. Users should rely on `google-cloud-compute` for modern API interactions.","severity":"deprecated","affected_versions":"2.x.x and earlier"},{"fix":"Ensure that any code attempting to access `metadata.google.internal` is executed on a running Google Compute Engine virtual machine instance. For external access to GCE resources, use the `google-cloud-compute` library and appropriate authentication.","message":"Metadata access relies on the HTTP metadata server (e.g., `http://metadata.google.internal`). This server is only accessible from within a Compute Engine VM instance. Attempting to query the metadata server from outside a GCE VM will result in connection errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If you intend to manage Compute Engine resources programmatically, install and use the `google-cloud-compute` library (`pip install google-cloud-compute`). If you need to interact with the VM's guest environment, ensure the package is installed on the VM and check the context of your import. Often, direct interaction with the metadata server (as shown in quickstart) is the intended pattern.","cause":"The `google-compute-engine` package is typically pre-installed on Google-provided Compute Engine OS images as a system component, or installed manually for VM-internal use. It is not usually imported by standard Python applications for external API calls, and trying to do so often indicates a misunderstanding of its purpose.","error":"ModuleNotFoundError: No module named 'google_compute_engine'"},{"fix":"Verify that your code is running inside a Google Compute Engine VM. If it is, check network connectivity or potential firewall rules that might be blocking access to the metadata server (though this is rare for the default internal endpoint). Ensure the URL `http://metadata.google.internal` is correct and accessible.","cause":"This error occurs when trying to access the metadata server URL (e.g., `http://metadata.google.internal`) from a machine that is not a Google Compute Engine VM, or if the metadata server is temporarily unavailable/unreachable within the VM.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', error(111, 'Connection refused'))"},{"fix":"Double-check the metadata path you are querying against the official Compute Engine metadata documentation. If accessing custom metadata, ensure the custom key has been correctly set for the instance or project via `gcloud compute instances add-metadata` or the Cloud Console.","cause":"You are trying to retrieve a metadata key or path that does not exist on the VM or in the project metadata. This could be a typo in the path or an attempt to access a custom metadata key that has not been set.","error":"HTTPError: 404 Client Error: Not Found for url: http://metadata.google.internal/computeMetadata/v1/instance/non-existent-key"}]}