Install & Compatibility
Where this runs
tested against v7.2.20 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.696s · 30.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.682s · 31MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Minio
✓ from minio import Minio
S3Error
✓ from minio.error import S3Error
✗ from minio.s3_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.
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}")
mc --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'minio'
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.
fixEnsure 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.
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.
fixVerify 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
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.
fixDouble-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')])")))
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.
fixIf 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'
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.
fixUpdate 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.
Upgrade
Version history
7.2.20latest on PyPI · released Nov 27, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.