{"id":759,"library":"gcloud-aio-storage","title":"gcloud-aio-storage","description":"gcloud-aio-storage is an asyncio-compatible Python client library for Google Cloud Storage. It provides full CRUD operations for buckets and blobs, including streaming support for large files, parallel upload capabilities, and built-in session management. Designed for high-performance cloud storage operations with modern async/await patterns, it is currently at version 9.6.4 and follows an active release cadence.","status":"active","version":"9.6.4","language":"python","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","gcs","async","aiohttp","cloud storage"],"install":[{"cmd":"pip install gcloud-aio-storage","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core async HTTP client used by the library.","package":"aiohttp","optional":false},{"reason":"Recommended for async file operations when interacting with local files.","package":"aiofiles","optional":true}],"imports":[{"symbol":"Storage","correct":"from gcloud.aio.storage import Storage"},{"symbol":"Bucket","correct":"from gcloud.aio.storage import Bucket"},{"symbol":"Blob","correct":"from gcloud.aio.storage import Blob"},{"symbol":"StreamResponse","correct":"from gcloud.aio.storage import StreamResponse"}],"quickstart":{"code":"import asyncio\nimport os\n\nfrom gcloud.aio.storage import Storage\n\nasync def main():\n    # GCLOUD_PROJECT, GOOGLE_APPLICATION_CREDENTIALS, or similar env vars\n    # should be set for authentication.\n    project_id = os.environ.get('GCLOUD_PROJECT', 'your-gcp-project-id')\n    bucket_name = 'your-gcs-bucket-name'\n    file_name = 'hello_gcloud_aio.txt'\n    content = b'Hello, gcloud-aio-storage!'\n\n    async with Storage(project=project_id) as storage:\n        print(f\"Uploading '{file_name}' to bucket '{bucket_name}'...\")\n        await storage.upload(bucket_name, file_name, content, content_type='text/plain')\n        print(f\"'{file_name}' uploaded successfully.\")\n\n        print(f\"Downloading '{file_name}' from bucket '{bucket_name}'...\")\n        downloaded_content = await storage.download(bucket_name, file_name)\n        print(f\"Downloaded content: {downloaded_content.decode()}\")\n\n        print(f\"Deleting '{file_name}' from bucket '{bucket_name}'...\")\n        await storage.delete(bucket_name, file_name)\n        print(f\"'{file_name}' deleted successfully.\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Set `contentType` with `charset=utf-8` in object metadata during upload, e.g., `content_type='application/json; charset=utf-8'`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.10 or newer. `gcloud-aio-storage` itself requires `>=3.10, <4.0`.","message":"Support 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.","severity":"breaking","affected_versions":"auth-5.4.4 and newer (indirectly affects storage)"},{"fix":"Upgrade to `gcloud-aio-storage` 9.6.4+ to benefit from bugfixes. Review your `auto_decompress` settings, especially if passing a custom `aiohttp.ClientSession`.","message":"Recent 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.","severity":"gotcha","affected_versions":"9.6.3 and older"},{"fix":"Structure custom metadata as `metadata={'metadata': {'foo': 'bar'}}`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use a 64-bit Python environment. For extremely large files, consider resumable uploads or streaming data in chunks.","message":"Users 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.","severity":"gotcha","affected_versions":"All versions (on 32-bit Python)"},{"fix":"Remove 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.","message":"The `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.","severity":"breaking","affected_versions":"A specific version of `gcloud-aio-storage` and newer (introduced in a recent major version update)"}],"env_vars":null,"last_verified":"2026-05-12T18:40:46.628Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure `gcloud-aio-storage` is installed via `pip install gcloud-aio-storage` and use the correct import statement: `from gcloud.aio.storage import Storage`.","cause":"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.","error":"from gcloud.aio.storage import Storage"},{"fix":"For 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.","cause":"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.","error":"OverflowError: string longer than 2147483647 bytes"},{"fix":"Increase 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.","cause":"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.","error":"TimeoutError"},{"fix":"Verify 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.","cause":"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).","error":"aiohttp.client_exceptions.ClientResponseError: 404, message='Not Found'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"9.6.4","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":null,"pypi_latest":"9.6.4","is_stale":null,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":16.9,"disk_size":"63.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.75,"mem_mb":16.7,"disk_size":"62.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":7.1,"import_time_s":0.54,"mem_mb":16.9,"disk_size":"65M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.57,"mem_mb":16.7,"disk_size":"65M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.92,"mem_mb":18.7,"disk_size":"72.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":18.6,"disk_size":"71.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":6.1,"import_time_s":0.79,"mem_mb":18.7,"disk_size":"75M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":18.6,"disk_size":"74M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":18.5,"disk_size":"66.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.12,"mem_mb":18.4,"disk_size":"66.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":5.2,"import_time_s":1.05,"mem_mb":18.5,"disk_size":"69M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.06,"mem_mb":18.4,"disk_size":"68M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.12,"mem_mb":19.4,"disk_size":"66.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":19.3,"disk_size":"65.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":5.3,"import_time_s":1.01,"mem_mb":19.3,"disk_size":"68M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.07,"mem_mb":19.3,"disk_size":"68M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":16.6,"disk_size":"48.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":16.7,"disk_size":"48.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":7.5,"import_time_s":0.65,"mem_mb":16.6,"disk_size":"51M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gcloud-aio-storage","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.64,"mem_mb":16.7,"disk_size":"51M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}