Install & Compatibility
Where this runs
tested against v6.3.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 0.000s · 46.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.3s · import 0.000s · 51MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Publisher
✓ from gcloud.aio.pubsub import Publisher
✗ from gcloud.aio.pubsub import Publisher
This quickstart demonstrates how to publish a message to a Pub/Sub topic and then subscribe to a subscription to receive and acknowledge a message using `gcloud-aio-pubsub`. It assumes you have `GCP_PROJECT` and `GCP_CREDENTIALS` environment variables set up, and that the specified topic and subscription already exist in your Google Cloud Project.
import asyncio
import json
import os
from aiohttp import ClientSession
from gcloud.aio.pubsub import Publisher, Subscriber
async def main():
# Ensure GCP_PROJECT and GCP_CREDENTIALS are set as environment variables.
# For local testing, GCP_CREDENTIALS should be the JSON key file content.
# Example: export GCP_CREDENTIALS=$(cat /path/to/keyfile.json)
project = os.environ.get('GCP_PROJECT', '')
if not project:
print("Error: GCP_PROJECT environment variable not set.")
return
topic_name = 'my-test-topic' # Replace with an existing topic
subscription_name = 'my-test-subscription' # Replace with an existing subscription
async with ClientSession() as session:
# --- Publisher Example ---
publisher = Publisher(session=session, project=project)
data = {'message': 'Hello, gcloud-aio-pubsub!'}
message_id = await publisher.publish(topic_name, [data])
print(f"Published message to '{topic_name}' with ID: {message_id}")
# --- Subscriber Example ---
subscriber = Subscriber(session=session, project=project)
print(f"Listening for messages on '{subscription_name}'...")
try:
# Fetch up to 1 message for this example
async for message in subscriber.subscribe(subscription_name, max_messages=1):
print(f"Received message: {message.data.decode('utf-8')}")
await message.ack()
print("Message acknowledged.")
break # Exit after first message for this quickstart
except Exception as e:
print(f"Error during subscription: {e}")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingAs of `gcloud-aio-auth` version 5.4.4 (a dependency of `gcloud-aio-pubsub`), support for Python 3.9 has been dropped. While `gcloud-aio-pubsub`'s `requires_python` might still indicate `>=3.9`, its transitive dependency on `gcloud-aio-auth>=5.4.4` means Python 3.9 is no longer supported across the `gcloud-aio` ecosystem.fixUpgrade your Python environment to 3.10 or newer.
affects: gcloud-aio-pubsub>=6.3.0, gcloud-aio-auth>=5.4.4
gotchaAll operations in `gcloud-aio-pubsub` are asynchronous. Ensure that all calls to `Publisher` and `Subscriber` methods are properly `await`ed, and that your code runs within an `async` context (e.g., using `asyncio.run()` or an `async` function).fixUse `await` before all async calls (e.g., `await publisher.publish(...)`, `async for message in subscriber.subscribe(...)`).
affects: All versions
gotchaAuthentication requires setting the `GCP_PROJECT` environment variable for your Google Cloud Project ID and `GCP_CREDENTIALS` with the full JSON string of your service account key. The client library does not automatically discover credentials from `gcloud auth login` or default service accounts without these variables for explicit `gcloud-aio` usage.fixSet `GCP_PROJECT` and `GCP_CREDENTIALS` (containing the JSON key file content) environment variables before running your application.
affects: All versions
gotchaProper `aiohttp.ClientSession` lifecycle management is crucial. It's recommended to create a single `ClientSession` per application and pass it to all `gcloud-aio` clients. Ensure the session is closed when no longer needed, typically using an `async with` statement.fixWrap `ClientSession()` creation in `async with ClientSession() as session:`, and pass `session=session` to `Publisher` and `Subscriber` constructors. If not using `async with` for the client itself, explicitly call `await client.close()`.
affects: All versions
Upgrade
Version history
6.3.0latest on PyPI · released Jul 17, 2025
Audit
Dependencies
aiohttprequiredCore HTTP client for asynchronous requests.
gcloud-aio-authrequiredHandles authentication with Google Cloud services.
gcloud-aio-corerequiredProvides shared utilities and base classes for gcloud-aio clients.
google-crc32crequiredUsed for CRC32C checksum calculations in Pub/Sub.
protobufrequiredHandles Google's Protocol Buffers for data serialization.