Install & Compatibility
Where this runs
tested against v1.25.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.974s · 71.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 1.288s · 70MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OsConfigServiceClient
✓ from google.cloud import osconfig_v1
OsConfigServiceAsyncClient
✓ from google.cloud import osconfig_v1
For asynchronous operations, the async client is also available within the same module.
This quickstart demonstrates how to instantiate the OS Config client and list patch jobs within a specified Google Cloud project. Ensure your `GCP_PROJECT_ID` environment variable is set and the OS Config API is enabled.
import os
from google.cloud import osconfig_v1
def list_patch_jobs():
# Set your Google Cloud Project ID as an environment variable or replace 'your-project-id'
project_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id')
if project_id == 'your-project-id':
print("Please set the 'GCP_PROJECT_ID' environment variable or replace 'your-project-id'.")
return
client = osconfig_v1.OsConfigServiceClient()
parent_path = f"projects/{project_id}"
request = osconfig_v1.ListPatchJobsRequest(
parent=parent_path,
)
try:
page_result = client.list_patch_jobs(request=request)
print(f"Patch jobs for project {project_id}:")
for response in page_result:
print(f" - {response.name} (State: {response.state.name})")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure the OS Config API is enabled for your project and your credentials are set up correctly.")
if __name__ == "__main__":
list_patch_jobs()
Debug
Known issues
breakingPython 3.9 is reaching or has reached End-of-Life (EOL) in late 2025/early 2026. While the PyPI `requires_python` currently indicates `>=3.9`, other Google Cloud client libraries are actively dropping official support for Python 3.9 as part of the monorepo's policy. Users on Python 3.9 should plan to upgrade to Python 3.10 or newer to ensure continued support and critical updates.fixUpgrade your Python environment to 3.10 or newer.
affects: All versions when used with Python 3.9
gotchaIncorrect Google Cloud authentication setup. Common issues include missing or improperly configured `GOOGLE_APPLICATION_CREDENTIALS` environment variable, or the service account/user lacking necessary IAM permissions (e.g., `osconfig.patchJobs.list`).fixRefer to Google Cloud authentication documentation. Ensure `GOOGLE_APPLICATION_CREDENTIALS` points to a valid service account key JSON file or that you are authenticated via `gcloud auth application-default login` with appropriate permissions for the OS Config API.
affects: All versions
gotchaMisconfigured resource paths for API calls. Resource names for Google Cloud APIs follow specific patterns (e.g., `projects/PROJECT_ID`, `projects/PROJECT_ID/locations/LOCATION_ID`). Incorrect formatting will result in `NotFound` or `InvalidArgument` errors.fixConsult the client library documentation or the Google Cloud API reference for the exact resource name format required by each method. For example, `ListPatchJobs` expects `projects/PROJECT_ID` as its parent argument.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud.osconfig'
The `google-cloud-os-config` Python client library is not installed in the current environment, or there's a problem with the Python environment's path.
fixInstall the library using pip: `pip install google-cloud-os-config`. Ensure you are installing it into the correct virtual environment if one is being used.
PermissionDenied
The service account or user credentials used by your application lack the necessary Identity and Access Management (IAM) permissions to interact with the Google Cloud OS Config API or the target VM instances.
fixGrant the required IAM roles to the service account or user, such as 'OS Config Service Agent' (`roles/osconfig.serviceAgent`), 'OS Config Agent' (`roles/osconfig.osConfigAgent`), 'Compute OS Admin Login' (`roles/compute.osAdminLogin`), 'Compute OS Login' (`roles/compute.osLogin`), 'OS Inventory Viewer' (`roles/osconfig.inventoryViewer`), and 'Service Usage Consumer' (`roles/serviceusage.serviceUsageConsumer`).
no agent was detected
The Google Cloud OS Config agent (usually referred to as the 'OS Config agent') is either not installed, not running, or not communicating with the OS Config API on the target Compute Engine VM instances where OS patch jobs or policies are being applied. This can also be caused by incorrect VM metadata or insufficient service account permissions.
fixVerify that the OS Config API is enabled in your Google Cloud project. Ensure the OS Config agent is installed and running on the VM instances. Check the VM metadata for `osconfig-disabled-features=tasks` and remove it if present. Confirm that the VM's attached service account has the necessary permissions for the OS Config agent to function correctly.
ModuleNotFoundError: No module named 'google.cloud.osconfig_v1'
The `google-cloud-os-config` library client is located under the `osconfig_v1` submodule, and directly importing `osconfig` or mistyping `osconfig_v1` leads to this error.
fixEnsure the library is installed (`pip install google-cloud-os-config`) and import the client correctly using `from google.cloud import osconfig_v1` or `import google.cloud.osconfig_v1`.
google.api_core.exceptions.PermissionDenied: 403 Permission denied
The credentials used for authentication lack the necessary IAM permissions to perform the requested operation on the OS Config API (e.g., listing, creating, or deleting patch deployments).
fixGrant the appropriate OS Config IAM role (e.g., `OS Config Editor`, `OS Config Admin`) to the service account or user principal used for authentication in the Google Cloud project.
Upgrade
Version history
1.25.0latest on PyPI · released Jun 22, 2026
Audit
Dependencies
google-api-corerequiredCore library for Google Cloud API clients, providing common functionalities like authentication, retries, and API request/response handling.
google-authrequiredHandles authentication with Google Cloud, including service account credentials and user authentication.