MinIO Python SDK

Common errors

• ModuleNotFoundError: No module named 'minio'

  cause The 'minio' package is not installed in your Python environment, or your script file is named 'minio.py', causing a name clash with the installed library.
  fix Ensure the MinIO SDK is installed using `pip install minio`. If you have a file named `minio.py`, rename it to something else (e.g., `my_minio_app.py`) to avoid module import conflicts.

• minio.error.S3Error: S3 operation failed; code: AccessDenied, message: Access Denied.

  cause The provided access key and secret key do not have the necessary permissions to perform the requested operation on the MinIO server or the specified bucket. This often relates to incorrect IAM policies or user credentials.
  fix Verify that your `access_key` and `secret_key` are correct and that the associated user or service account has the appropriate bucket and object policies (e.g., `s3:GetObject`, `s3:PutObject`, `s3:ListBucket`) on the MinIO server. If using a custom policy, ensure it explicitly grants the required actions.

• minio.error.S3Error: S3 operation failed; code: NoSuchKey, message: Object does not exist

  cause You are attempting to access an object with a key (path and name) that does not exist in the specified bucket. This can be due to a typo in the object name, case sensitivity issues, or the object having been deleted or moved.
  fix Double-check the `object_name` and `bucket_name` for accuracy, including case sensitivity. Use `client.list_objects()` to verify the exact key of the object you intend to access. If the object was recently created, ensure it has been fully uploaded.

• HTTPSConnectionPool(host='...', port=...): Max retries exceeded with url: ... (Caused by SSLError(SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')])")))

  cause This error indicates a problem with the SSL/TLS certificate verification when trying to establish a secure connection to the MinIO server. It often happens when the server uses a self-signed certificate or one not trusted by the client's system.
  fix If you are using a self-signed certificate or connecting to a test environment where certificate verification is not critical, you can disable SSL verification by setting `secure=False` in the Minio client constructor. For production, ensure your client system trusts the server's certificate or provide a custom `cert_check` option with your CA certificates.

• ImportError: cannot import name 'S3Error' from 'minio.error'

  cause This error occurs because the `S3Error` class was introduced or moved in a specific version of the `minio` library (e.g., from version 7.0.0 onwards). Your installed `minio` version is likely older.
  fix Update your `minio` Python library to the latest version, or at least to version 7.0.0 or higher, using `pip install --upgrade minio`. If you need to support older versions, you might need to adjust your error handling to catch `minio.error.ResponseError` or a more general `minio.error.MinioException` if `S3Error` is not available.

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
  wrong:

  from minio.s3_error import S3Error

  correct:

  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}")