Install & Compatibility
Where this runs
tested against v9.6.4 · 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.910s · 49.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 0.832s · 54MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Storage
✓ from gcloud.aio.storage import Storage
Bucket
✓ from gcloud.aio.storage import Bucket
Blob
✓ from gcloud.aio.storage import Blob
StreamResponse
✓ from gcloud.aio.storage import StreamResponse
This quickstart demonstrates how to initialize the Storage client, upload a byte string, download it, and then delete the object. Ensure that Google Cloud authentication (e.g., via `GOOGLE_APPLICATION_CREDENTIALS` environment variable) and the `GCLOUD_PROJECT` environment variable are set, or provide them as arguments to the `Storage` client.
import asyncio
import os
from gcloud.aio.storage import Storage
async def main():
# GCLOUD_PROJECT, GOOGLE_APPLICATION_CREDENTIALS, or similar env vars
# should be set for authentication.
project_id = os.environ.get('GCLOUD_PROJECT', 'your-gcp-project-id')
bucket_name = 'your-gcs-bucket-name'
file_name = 'hello_gcloud_aio.txt'
content = b'Hello, gcloud-aio-storage!'
async with Storage(project=project_id) as storage:
print(f"Uploading '{file_name}' to bucket '{bucket_name}'...")
await storage.upload(bucket_name, file_name, content, content_type='text/plain')
print(f"'{file_name}' uploaded successfully.")
print(f"Downloading '{file_name}' from bucket '{bucket_name}'...")
downloaded_content = await storage.download(bucket_name, file_name)
print(f"Downloaded content: {downloaded_content.decode()}")
print(f"Deleting '{file_name}' from bucket '{bucket_name}'...")
await storage.delete(bucket_name, file_name)
print(f"'{file_name}' deleted successfully.")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
gotchaWhen downloading large files and using `response.text()`, `aiohttp` (which `gcloud-aio-storage` uses) may default to `chardet` for character encoding detection, which can be very slow. Explicitly setting the `Content-Type` with a `charset` (e.g., `text/plain; charset=utf-8`) when uploading can significantly improve performance for text-based files.fixSet `contentType` with `charset=utf-8` in object metadata during upload, e.g., `content_type='application/json; charset=utf-8'`.
affects: All versions
breakingSupport for Python 3.9 was dropped in the `gcloud-aio-auth` component (version 5.4.4) of the `gcloud-aio` ecosystem. While this specifically refers to `gcloud-aio-auth`, it's generally indicative of the overall library's compatibility, so users on Python 3.9 attempting to upgrade other `gcloud-aio` components might encounter issues.fixUpgrade your Python environment to 3.10 or newer. `gcloud-aio-storage` itself requires `>=3.10, <4.0`.
affects: auth-5.4.4 and newer (indirectly affects storage)
gotchaRecent releases include fixes related to `auto_decompress` handling in `download_stream` and `ClientSession` settings. Ensure you are not inadvertently overwriting or misconfiguring `auto_decompress` if you have custom `aiohttp.ClientSession` settings.fixUpgrade to `gcloud-aio-storage` 9.6.4+ to benefit from bugfixes. Review your `auto_decompress` settings, especially if passing a custom `aiohttp.ClientSession`.
affects: 9.6.3 and older
gotchaWhen passing custom metadata during an `upload()` operation, ensure it's nested under a 'metadata' key in the dictionary. Incorrectly structured metadata (e.g., top-level key-value pairs) will not be stored as custom metadata.fixStructure custom metadata as `metadata={'metadata': {'foo': 'bar'}}`. affects: All versions
gotchaUsers have reported issues uploading files larger than 2GB, particularly when running on 32-bit Python installations. This is a common limitation for 32-bit systems regarding file sizes and memory addressing.fixUse a 64-bit Python environment. For extremely large files, consider resumable uploads or streaming data in chunks.
affects: All versions (on 32-bit Python)
breakingThe `Storage` class constructor no longer accepts a `project` keyword argument. The library is designed to infer the project ID from the environment (e.g., `GOOGLE_CLOUD_PROJECT` environment variable) or from default credentials configured in the execution environment.fixRemove the `project` argument from the `Storage` constructor. Ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set, or that the application is running in an environment where default credentials are correctly configured for the desired Google Cloud Project.
affects: A specific version of `gcloud-aio-storage` and newer (introduced in a recent major version update)
Errors
Common errors & fixes
from gcloud.aio.storage import Storage
The 'gcloud-aio-storage' library, specifically its `Storage` class, is imported incorrectly, often due to a typo in the module path or the library not being installed.
fixEnsure `gcloud-aio-storage` is installed via `pip install gcloud-aio-storage` and use the correct import statement: `from gcloud.aio.storage import Storage`.
OverflowError: string longer than 2147483647 bytes
This error typically occurs when attempting to upload a very large file (over 2GB) by reading its entire content into a Python string, which can exceed memory limits or Python's string size limitations, especially on 32-bit systems. The `gcloud-aio-storage` library, depending on how it's used, might try to buffer the entire file content.
fixFor large files, use streaming uploads or upload in chunks. Instead of reading the entire file into memory as a string, pass a file-like object or an asynchronous generator that yields bytes to the upload function, allowing the library to handle the data in smaller parts.
TimeoutError
This error occurs when a network operation, such as uploading or downloading a file, exceeds the default or specified timeout duration. This can be caused by large file sizes, slow network connections, or insufficient timeout settings.
fixIncrease the `timeout` parameter in your `gcloud.aio.storage` method calls (e.g., `client.upload(..., timeout=300)` for 300 seconds) or ensure that your network connection is stable and sufficiently fast for the operation.
aiohttp.client_exceptions.ClientResponseError: 404, message='Not Found'
This 'Not Found' error usually indicates that the specified Google Cloud Storage bucket or object does not exist, or that there's an issue with the GCS emulator setup (e.g., the emulator is running but the target bucket hasn't been created within it).
fixVerify that the bucket name and object path are correct and exist in your Google Cloud Project. If using a GCS emulator, ensure the emulator is running and the bucket you're trying to access or create has been provisioned in the emulator before making requests.
Upgrade
Version history
9.6.4latest on PyPI · released Feb 26, 2026
Audit
Dependencies
aiohttprequiredCore async HTTP client used by the library.
aiofilesoptionalRecommended for async file operations when interacting with local files.