{"id":9946,"library":"miniopy-async","title":"Asynchronous MinIO Client SDK","description":"miniopy-async provides an asynchronous interface to the MinIO object storage server, building upon the official synchronous `minio` Python client by integrating `aiohttp`. It aims to stay up-to-date with `minio-py`'s features while providing `asyncio` compatibility. The current version is 1.23.5, and it maintains a frequent release cadence, often aligning with updates to the underlying `minio-py` library or addressing async-specific bugs.","status":"active","version":"1.23.5","language":"en","source_language":"en","source_url":"https://github.com/hlf20010508/miniopy-async","tags":["minio","s3","cloud storage","asynchronous","aiohttp"],"install":[{"cmd":"pip install miniopy-async","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the asynchronous HTTP client necessary for async operations.","package":"aiohttp","optional":false},{"reason":"The core synchronous MinIO client which `miniopy-async` wraps for async functionality.","package":"minio","optional":false}],"imports":[{"note":"Using 'minio' directly will import the synchronous client, not the async wrapper.","wrong":"from minio import Minio","symbol":"Minio","correct":"from miniopy_async import Minio"},{"note":"While 'minio.error.S3Error' exists, it's best to import from 'miniopy_async' for consistency.","wrong":"from minio.error import S3Error","symbol":"S3Error","correct":"from miniopy_async import S3Error"}],"quickstart":{"code":"import os\nimport asyncio\nfrom miniopy_async import Minio, S3Error\n\nasync def main():\n    endpoint = os.environ.get(\"MINIO_ENDPOINT\", \"localhost:9000\")\n    access_key = os.environ.get(\"MINIO_ACCESS_KEY\", \"minioadmin\")\n    secret_key = os.environ.get(\"MINIO_SECRET_KEY\", \"minioadmin\")\n    secure = os.environ.get(\"MINIO_SECURE\", \"false\").lower() == \"true\"\n\n    client = Minio(\n        endpoint=endpoint,\n        access_key=access_key,\n        secret_key=secret_key,\n        secure=secure\n    )\n\n    try:\n        # Example: List all buckets\n        buckets = await client.list_buckets()\n        print(f\"Successfully connected to MinIO. Found {len(buckets)} buckets:\")\n        for bucket in buckets:\n            print(f\"  - {bucket.name} (created at {bucket.creation_date})\")\n\n        # Example: Make a bucket if it doesn't exist\n        test_bucket = \"my-test-bucket\"\n        found = await client.bucket_exists(test_bucket)\n        if not found:\n            await client.make_bucket(test_bucket)\n            print(f\"Bucket '{test_bucket}' created successfully.\")\n        else:\n            print(f\"Bucket '{test_bucket}' already exists.\")\n\n    except S3Error as e:\n        print(f\"MinIO S3 Error: {e.code} - {e.message}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    # Ensure MinIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY are set\n    # or MinIO is running locally with default credentials (minioadmin:minioadmin)\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to initialize the `Minio` client, list existing buckets, and create a new bucket asynchronously. Ensure your MinIO server endpoint and credentials are provided via environment variables or directly in the code for execution."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer to ensure full compatibility and access to all features.","message":"Python 3.8 and 3.9 are deprecated and no longer officially supported due to type hinting requirements.","severity":"breaking","affected_versions":">=1.21.3"},{"fix":"Always prefix calls to `miniopy_async.Minio` methods (e.g., `client.list_buckets()`, `client.put_object()`) with the `await` keyword within an `async` function.","message":"All `miniopy-async` methods are coroutines and *must* be `await`ed. Forgetting `await` will result in a `TypeError` or unexpected behavior.","severity":"gotcha","affected_versions":"All"},{"fix":"If generating presigned URLs and needing to specify a different host, use the `server_url` parameter in the `Minio` constructor instead of deprecated methods.","message":"The `Minio` constructor gained a `server_url` parameter, intended to replace `change_host` for specifying the server endpoint for presigned URLs.","severity":"breaking","affected_versions":">=1.22.1"},{"fix":"Ensure that `content-length-range` values are passed as strings, e.g., `['1', '10485760']`, rather than integers.","message":"The `content-length-range` format for policy conditions in presigned URLs changed from integers to strings.","severity":"gotcha","affected_versions":">=1.23.5"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure all calls to `miniopy-async` methods are prefixed with `await` (e.g., `await client.list_buckets()`). Also, ensure your main execution flow uses `asyncio.run(your_async_main_function())`.","cause":"Attempting to call an asynchronous `miniopy-async` method without the `await` keyword, or calling an async function in a synchronous context.","error":"TypeError: object asyncio.coroutine can't be used in 'await' expression"},{"fix":"Verify that your MinIO server is running and accessible. Double-check the `endpoint` (e.g., `localhost:9000`) used when creating the `Minio` client instance.","cause":"The MinIO server is either not running, not accessible from your environment, or the `endpoint` specified in `Minio` client initialization is incorrect (e.g., wrong host or port).","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"fix":"Check the bucket name for accuracy. If you intend to create the bucket, ensure your credentials have the necessary permissions and call `client.make_bucket()` first.","cause":"An operation was attempted on a MinIO bucket that does not exist, or the bucket name provided has a typo.","error":"miniopy_async.S3Error: [{'Code': 'NoSuchBucket', 'Message': 'The specified bucket does not exist'}]"}]}