Install & Compatibility
Where this runs
tested against v2.4.0.20260518 · 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.940 runs
installs and imports cleanly · install 0.0s · import 2.188s · 17.9MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.9s · import 1.557s · 214MB
143MB installed
● package 143MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ndb
✓ from google-stubs import ndb
✗ from google-stubs import ndb
This quickstart demonstrates basic CRUD operations using `google-cloud-ndb` with `async/await` and context management. Installing `types-google-cloud-ndb` alongside `google-cloud-ndb` will enable your type checker to provide rich completions and error detection for this code, enhancing developer experience. Ensure you have the Cloud Datastore emulator running for local testing and `GOOGLE_CLOUD_PROJECT` environment variable set for deployment.
import os
from google.cloud import ndb
import asyncio
# For local development, point to the Datastore emulator
os.environ['DATASTORE_EMULATOR_HOST'] = os.environ.get('DATASTORE_EMULATOR_HOST', 'localhost:8081')
# Ensure your GOOGLE_CLOUD_PROJECT is set, e.g., in your environment or 'your-gcp-project-id'
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')
class User(ndb.Model):
name = ndb.StringProperty()
email = ndb.StringProperty()
joined_date = ndb.DateTimeProperty(auto_now_add=True)
async def main():
client = ndb.Client(project=project_id)
async with client.context():
# Create a user
user = User(name='Alice', email='alice@example.com')
user_key = await user.put()
print(f'Created user with key: {user_key.id()}')
# Fetch the user back by key
fetched_user = await user_key.get_async()
if fetched_user:
print(f'Fetched user: {fetched_user.name} ({fetched_user.email})')
# Query for users
query = User.query(User.name == 'Alice')
users_with_name = await query.fetch_async(limit=1)
if users_with_name:
print(f'Query result: {users_with_name[0].name}')
# Update user
if fetched_user:
fetched_user.email = 'alice.updated@example.com'
await fetched_user.put()
print(f'Updated user: {fetched_user.email}')
# Delete user
await user_key.delete_async()
print(f'Deleted user with key: {user_key.id()}')
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingMigration from the original App Engine NDB (`google.appengine.ext.ndb`) to `google-cloud-ndb` (which these stubs type) requires significant code changes. This library is a standalone client for Cloud Datastore, not a direct drop-in replacement for App Engine apps. Key differences include package name, mandatory `async/await` for most operations, and different client initialization and context management.fixRewrite application logic to use `google.cloud.ndb` imports, adapt to `async/await` patterns, and implement new client and context management. Consult the official `google-cloud-ndb` migration guides.
affects: All versions when migrating from legacy App Engine NDB
gotchaAll NDB database operations (e.g., `put()`, `get()`, `fetch()`) are asynchronous and return 'futures'. Forgetting to `await` these operations will result in the operation not being executed, or returning the future object itself rather than its result.fixAlways use `await` before any NDB operation that interacts with the Datastore, such as `await entity.put()`, `await key.get_async()`, `await query.fetch_async()`, etc.
affects: All versions of `google-cloud-ndb`
gotchaAll Datastore interactions must occur within an NDB context. Failing to establish a context (or letting it expire) will raise a `RuntimeError: A context is required for this operation.`fixFor `async` code, use `async with client.context():`. For non-`async` code, use the `@ndb.toplevel` decorator or explicitly enter/exit the context using `context = client.context(); context.__enter__(); try: ... finally: context.__exit__(None, None, None)`.
affects: All versions of `google-cloud-ndb`
gotchaThe `types-google-cloud-ndb` package provides *only* type annotations. It does not contain any executable code. Importing symbols from `types_google_cloud_ndb` for runtime use will result in `ModuleNotFoundError` or `AttributeError`.fixAlways import NDB symbols from `google.cloud.ndb`. The `types-google-cloud-ndb` package is consumed solely by type checkers.
affects: All versions
gotchaWhile `types-google-cloud-ndb` aims to provide accurate annotations for `google-cloud-ndb==2.4.*`, significant discrepancies between the stub version and the runtime library version can lead to incorrect type checking results or missed errors.fixKeep `types-google-cloud-ndb` and `google-cloud-ndb` versions as close as possible. The stub's version (e.g., `2.4.0.20260408`) indicates it targets `google-cloud-ndb==2.4.*`. Regularly update both packages to their latest compatible versions.
affects: All versions
deprecatedCloud NDB is primarily intended as a migration path for applications moving from App Engine NDB. For *new* Python 3 applications that require Datastore, Google recommends using the native Cloud Datastore client library (`google-cloud-datastore`) instead of Cloud NDB, as it supports newer Firestore in Datastore mode features.fixFor greenfield Python 3 projects or new features, consider using `google-cloud-datastore`. If migrating an existing App Engine NDB app, Cloud NDB remains a viable intermediate step.
affects: All versions of `google-cloud-ndb`
Upgrade
Version history
2.4.0.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
google-cloud-ndbrequiredThis package provides type stubs for google-cloud-ndb; it does not provide runtime functionality itself.