MinIO Python SDK

7.2.20 · active · verified Thu Apr 09

The MinIO Python SDK provides idiomatic bindings for interacting with MinIO and Amazon S3 compatible cloud storage services. It offers a comprehensive set of APIs for object storage operations like putting, getting, and listing objects, as well as bucket management. The library is actively maintained with frequent bugfix and feature releases, typically on a weekly or bi-weekly cadence.

Warnings

breaking Python 3.8 support was removed in MinIO SDK version 7.2.11. Users on Python 3.8 or older will need to upgrade their Python interpreter to 3.9+ to use newer SDK versions.
Fix: Upgrade your Python environment to 3.9 or higher.
gotcha The `Minio` client defaults to `secure=True` for HTTPS connections. If connecting to a local or self-signed MinIO instance via HTTP, you must explicitly set `secure=False`.
Fix: Initialize the client with `secure=False`: `client = Minio(..., secure=False)`
gotcha The `Minio.make_bucket()` method will raise a `BucketAlreadyOwnedByYou` error if the bucket already exists. It's often safer to check for existence first or handle the specific exception.
Fix: Before calling `make_bucket`, check `if not client.bucket_exists(bucket_name): client.make_bucket(bucket_name)` or wrap `make_bucket` in a `try...except S3Error as e: if e.code == 'BucketAlreadyOwnedByYou': ...` block.
gotcha All MinIO-specific errors are derived from `minio.error.S3Error`. For robust error handling, catch this specific exception.
Fix: Use `from minio.error import S3Error` and wrap your MinIO operations in a `try...except S3Error as e:` block.

Install

pip install minio Install stable version

Imports

Minio
```
from minio import Minio
```
S3Error
```
from minio.error import S3Error
```
S3Error was moved to minio.error in earlier versions, always import from minio.error.
MinioAdmin
```
from minio.admin import MinioAdmin
```
For administrative tasks like user management, policies, etc.

Quickstart

This quickstart initializes a MinIO client, creates a bucket if it doesn't exist, uploads a text file as an object, and then downloads it, printing the content. Ensure `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, and optionally `MINIO_SECURE` environment variables are set for authentication, or provide them directly. The default endpoint `play.min.io` is a public MinIO sandbox.

import os
import io
from minio import Minio
from minio.error import S3Error

try:
    # Initialize MinIO client
    client = Minio(
        endpoint=os.environ.get("MINIO_ENDPOINT", "play.min.io: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", "true").lower() == "true"
    )

    bucket_name = "my-test-bucket-123"
    object_name = "my-file.txt"
    file_content = b"Hello, MinIO from Python SDK!"

    # Check if bucket exists, create if not
    if not client.bucket_exists(bucket_name):
        client.make_bucket(bucket_name)
        print(f"Bucket '{bucket_name}' created.")
    else:
        print(f"Bucket '{bucket_name}' already exists.")

    # Upload data to an object
    client.put_object(
        bucket_name,
        object_name,
        data=io.BytesIO(file_content),
        length=len(file_content),
        content_type="text/plain"
    )
    print(f"Object '{object_name}' uploaded to bucket '{bucket_name}'.")

    # Download data from an object
    data_stream = client.get_object(bucket_name, object_name)
    downloaded_content = data_stream.read()
    print(f"Downloaded content: {downloaded_content.decode('utf-8')}")

    assert downloaded_content == file_content
    print("Download successful and content matched.")

except S3Error as e:
    print(f"MinIO S3 error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →