Install & Compatibility
Where this runs
tested against v1.23.5 · 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
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Minio
✓ from miniopy_async import Minio
✗ from minio import Minio
Using 'minio' directly will import the synchronous client, not the async wrapper.
S3Error
✓ from miniopy_async import S3Error
✗ from minio.error import S3Error
While 'minio.error.S3Error' exists, it's best to import from 'miniopy_async' for consistency.
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.
import os
import asyncio
from miniopy_async import Minio, S3Error
async def main():
endpoint = os.environ.get("MINIO_ENDPOINT", "localhost:9000")
access_key = os.environ.get("MINIO_ACCESS_KEY", "minioadmin")
secret_key = os.environ.get("MINIO_SECRET_KEY", "minioadmin")
secure = os.environ.get("MINIO_SECURE", "false").lower() == "true"
client = Minio(
endpoint=endpoint,
access_key=access_key,
secret_key=secret_key,
secure=secure
)
try:
# Example: List all buckets
buckets = await client.list_buckets()
print(f"Successfully connected to MinIO. Found {len(buckets)} buckets:")
for bucket in buckets:
print(f" - {bucket.name} (created at {bucket.creation_date})")
# Example: Make a bucket if it doesn't exist
test_bucket = "my-test-bucket"
found = await client.bucket_exists(test_bucket)
if not found:
await client.make_bucket(test_bucket)
print(f"Bucket '{test_bucket}' created successfully.")
else:
print(f"Bucket '{test_bucket}' already exists.")
except S3Error as e:
print(f"MinIO S3 Error: {e.code} - {e.message}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
if __name__ == "__main__":
# Ensure MinIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY are set
# or MinIO is running locally with default credentials (minioadmin:minioadmin)
asyncio.run(main())
Errors
Common errors & fixes
TypeError: object asyncio.coroutine can't be used in 'await' expression
Attempting to call an asynchronous `miniopy-async` method without the `await` keyword, or calling an async function in a synchronous context.
fixEnsure 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())`.
ConnectionRefusedError: [Errno 111] Connection refused
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).
fixVerify that your MinIO server is running and accessible. Double-check the `endpoint` (e.g., `localhost:9000`) used when creating the `Minio` client instance.
miniopy_async.S3Error: [{'Code': 'NoSuchBucket', 'Message': 'The specified bucket does not exist'}]
An operation was attempted on a MinIO bucket that does not exist, or the bucket name provided has a typo.
fixCheck 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.
Upgrade
Version history
1.23.5latest on PyPI · released Mar 31, 2026
Audit
Dependencies
aiohttprequiredProvides the asynchronous HTTP client necessary for async operations.
miniorequiredThe core synchronous MinIO client which `miniopy-async` wraps for async functionality.