Install & Compatibility
Where this runs
tested against v9.1.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.920 runs
installs and imports cleanly · install 0.0s · import 0.759s · 60.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.6s · import 0.703s · 62MB
61MB installed
● package 61MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Datastore
✓ from gcloud.aio.datastore import Datastore
Key
✓ from gcloud.aio.datastore import Key
Query
✓ from gcloud.aio.datastore import Query
This quickstart demonstrates how to initialize the Datastore client using service account credentials, create, retrieve, and query entities. Ensure `GCP_PROJECT` is set to your Google Cloud project ID and `GCP_SERVICE_KEY` is set to your service account key JSON string (or path via `GCP_SERVICE_KEY_PATH`) in the environment. The client uses `async with` for proper resource management.
import asyncio
import os
from gcloud.aio.auth import build_from_service_account
from gcloud.aio.datastore import Datastore, Key, Query
async def main():
project = os.environ.get('GCP_PROJECT', 'your-gcp-project-id')
service_account_info = os.environ.get('GCP_SERVICE_KEY') # or path via GCP_SERVICE_KEY_PATH
if not project or not service_account_info:
print("Please set GCP_PROJECT and GCP_SERVICE_KEY environment variables.")
return
# Credentials can also be built from a path using build_from_service_account_path()
creds = build_from_service_account(service_account_info)
async with Datastore(project=project, credentials=creds) as client:
# 1. Create an entity
kind = 'MyEntity'
name = 'my-unique-entity-name'
key = Key([kind, name], project=project)
entity_data = {
'property1': 'value1',
'property2': 123
}
await client.put_entity(key, entity_data)
print(f"Created/updated entity: {key.path[0]['id']}")
# 2. Get an entity
retrieved_entity = await client.get_entity(key)
if retrieved_entity:
print(f"Retrieved entity: {retrieved_entity.properties}")
else:
print(f"Entity {key.path[0]['id']} not found.")
# 3. Run a query
query = Query(kind=kind, project=project)
results = await client.run_query(query)
print("Query results:")
for entity in results:
print(f" Kind: {entity.kind}, ID: {entity.id}, Properties: {entity.properties}")
# 4. Delete an entity (optional cleanup)
# await client.delete_entity(key)
# print(f"Deleted entity: {key.path[0]['id']}")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingPython 3.9 support was dropped by `gcloud-aio-auth` in version `5.4.4`. While `gcloud-aio-datastore 9.1.0` lists `Python >= 3.9` as compatible, installing `gcloud-aio-auth >= 5.4.4` (which is within `gcloud-aio-datastore`'s dependency range `<6.0.0,>=5.0.0`) will lead to compatibility issues for Python 3.9 users.fixUpgrade your Python environment to 3.10 or newer. If you must use Python 3.9, pin `gcloud-aio-auth` to `<5.4.4` (e.g., `gcloud-aio-auth<5.4.4,>=5.0.0`) in your requirements, although this might prevent future security updates for `gcloud-aio-auth`.
affects: gcloud-aio-datastore >= 9.1.0 (when combined with gcloud-aio-auth >= 5.4.4)
breakingVersion 9.0.0 of `gcloud-aio-datastore` removed the `Datastore.from_service_account()` and `Datastore.from_dict()` convenience constructors. Authentication should now be handled explicitly by building credentials via `gcloud.aio.auth.build_from_service_account()` and passing them to the `Datastore` client constructor.fixMigrate your authentication setup to use `gcloud.aio.auth.build_from_service_account()` and pass the resulting credentials object directly to the `Datastore` constructor. Refer to the quickstart example for the updated pattern.
affects: gcloud-aio-datastore >= 9.0.0
gotchaThis library is entirely asynchronous (`aio`). All client methods are `await`able coroutines and must be called within an `asyncio` event loop. Attempting to call them synchronously will result in `RuntimeError: 'coroutine' object is not awaited`.fixEnsure your code uses `async def` functions and `await` for all `gcloud-aio-datastore` calls. Run your main `async` function using `asyncio.run()`.
affects: All versions
gotchaThe `gcloud-aio` project is a monorepo, meaning individual client libraries like `gcloud-aio-datastore`, `gcloud-aio-storage`, and `gcloud-aio-auth` have independent versioning. Upgrading one component does not automatically upgrade others, and you must manage dependencies for each sub-package carefully to avoid version conflicts or unexpected behavior.fixAlways check the `requires_dist` for specific `gcloud-aio-*` packages on PyPI to understand their compatible version ranges for dependencies. Use a dependency manager like `pip-tools` or `Poetry` to ensure a consistent environment.
affects: All versions
gotchaAuthentication relies on `gcloud-aio-auth`. It primarily supports service account keys (JSON string or path). Ensure `GCP_PROJECT` and `GCP_SERVICE_KEY` (or `GCP_SERVICE_KEY_PATH`) environment variables are correctly configured or explicitly passed to `build_from_service_account`.fixVerify your environment variables or direct arguments for authentication. Debug authentication issues by ensuring `build_from_service_account` successfully returns credentials before initializing the Datastore client.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gcloud.aio.datastore'
This error occurs when the `gcloud-aio-datastore` package is not installed or is not accessible in the current Python environment.
fixEnsure the library is correctly installed using pip: `pip install gcloud-aio-datastore` or if using `gcloud-rest-datastore`, `pip install gcloud-rest-datastore`.
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.
This error indicates that your application cannot find the necessary Google Cloud credentials to authenticate with Datastore, often due to missing `GOOGLE_APPLICATION_CREDENTIALS` environment variable or not having run `gcloud auth application-default login`.
fixSet the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file (e.g., `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`), or authenticate via the gcloud CLI by running `gcloud auth application-default login`.
TypeError: object ... is not awaitable
This error happens when you call an asynchronous function (coroutine) from `gcloud-aio-datastore` without using the `await` keyword, which is required for `asyncio` operations.
fixPrepend the call to the asynchronous function with `await`. For example, instead of `client.get(key)`, use `await client.get(key)`. Ensure your code runs within an `async` function and an `asyncio` event loop.
AttributeError: module 'grpc.experimental.aio' has no attribute 'StreamUnaryCall'
This `AttributeError` typically arises from a version incompatibility between the `google-cloud-datastore` library (which `gcloud-aio-datastore` wraps) and its `grpcio` dependency. It suggests that a newer version of `google-cloud-datastore` expects a `grpcio` feature that an older `grpcio` version does not provide.
fixPin `google-api-core` to a compatible version (e.g., `google-api-core==1.17.0`) and/or ensure `grpcio` and `google-cloud-datastore` are updated to their latest compatible versions by running `pip install --upgrade google-cloud-datastore grpcio` and checking the project's dependencies for specific requirements.
Upgrade
Version history
9.1.0latest on PyPI · released Aug 26, 2025
Audit
Dependencies
gcloud-aio-authrequiredHandles authentication for all gcloud-aio clients.
gcloud-aio-corerequiredProvides core utilities and base classes for gcloud-aio clients.
google-cloud-datastorerequiredUnderlying synchronous Google Cloud Datastore client, which gcloud-aio-datastore wraps.