Python Client API Reference Slack

Initialize MinIO Client object.

MinIO

from minio import Minio
from minio.error import ResponseError

minioClient = Minio(
    'play.min.io',
    access_key='Q3AM3UQ867SPQQA43P2F',
    secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
    secure=True,
)

AWS S3

from minio import Minio
from minio.error import ResponseError

s3Client = Minio(
    's3.amazonaws.com',
    access_key='YOUR-ACCESSKEYID',
    secret_key='YOUR-SECRETACCESSKEY',
    secure=True,
)
Bucket operations Object operations Presigned operations Bucket policy/notification/encryption operations
make_bucket get_object presigned_get_object get_bucket_policy
list_buckets put_object presigned_put_object set_bucket_policy
bucket_exists copy_object presigned_post_policy delete_bucket_policy
remove_bucket stat_object get_bucket_notification
list_objects remove_object set_bucket_notification
enable_bucket_versioning remove_objects remove_all_bucket_notification
disable_bucket_versioning fput_object listen_bucket_notification
fget_object get_bucket_encryption
select_object_content put_bucket_encryption
delete_bucket_encryption

1. Constructor

Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None)

Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None)
Initializes a new client object.

Parameters

Param Type Description
endpoint str Hostname of a S3 service.
access_key str (Optional) Access key (aka user ID) of your account in S3 service.
secret_key str (Optional) Secret Key (aka password) of your account in S3 service.
session_token str (Optional) Session token of your account in S3 service.
secure bool (Optional) Flag to indicate to use secure (TLS) connection to S3 service or not.
region str (Optional) Region name of buckets in S3 service.
http_client urllib3.poolmanager.PoolManager (Optional) Customized HTTP client.
credentials minio.credentials.Credentials (Optional) Credentials of your account in S3 service.

NOTE on concurrent usage: The Minio object is thread safe when using the Python threading library. Specifically, it is NOT safe to share it between multiple processes, for example when using multiprocessing.Pool. The solution is simply to create a new Minio object in each process, and not share it between processes.

Example

MinIO

from minio import Minio
from minio.error import ResponseError

minioClient = Minio(
    'play.min.io',
    access_key='Q3AM3UQ867SPQQA43P2F',
    secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
)

NOTE: If there is a corporate proxy, specify a custom httpClient using urllib3.ProxyManager as shown below:

from minio import Minio
from minio.error import ResponseError
import urllib3

httpClient = urllib3.ProxyManager(
    'https://proxy_host.sampledomain.com:8119/',
    timeout=urllib3.Timeout.DEFAULT_TIMEOUT,
    cert_reqs='CERT_REQUIRED',
    retries=urllib3.Retry(
        total=5,
        backoff_factor=0.2,
        status_forcelist=[500, 502, 503, 504],
    )
)

minioClient = Minio(
    'your_hostname.sampledomain.com:9000',
    access_key='ACCESS_KEY',
    secret_key='SECRET_KEY',
    secure=True,
    http_client=httpClient,
)

AWS S3

from minio import Minio
from minio.error import ResponseError

s3Client = Minio(
    's3.amazonaws.com',
    access_key='ACCESS_KEY',
    secret_key='SECRET_KEY',
)

2. Bucket operations

make_bucket(self, bucket_name, location='us-east-1', object_lock=False)

Create a bucket with region and object lock.

Parameters

Param Type Description
bucket_name str Name of the bucket.
location str Region in which the bucket will be created.
object_lock bool Flag to set object-lock feature.

Example

minio.make_bucket('foo')
minio.make_bucket('foo', 'us-west-1')
minio.make_bucket('foo', 'us-west-1', object_lock=True)

list_buckets()

List information of all accessible buckets.

Parameters

Return
An iterator contains bucket information.

Example

bucket_list = minio.list_buckets()
for bucket in bucket_list:
    print(bucket.name, bucket.created_date)

bucket_exists(bucket_name)

Check if a bucket exists.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

found = minio.bucket_exists("my-bucketname")
if found:
    print("my-bucketname exists")
else:
    print("my-bucketname does not exist")

remove_bucket(bucket_name)

Remove an empty bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

minio.remove_bucket("my-bucketname")

list_objects(bucket_name, prefix=None, recursive=False, include_version=False)

Lists object information of a bucket using S3 API version 1, optionally for prefix recursively.

Parameters

Param Type Description
bucket_name str Name of the bucket.
prefix str Object name starts with prefix.
recursive bool List recursively than directory structure emulation.
include_version bool Flag to control whether include object versions.

Return Value

Return
An iterator contains object information as minio.Object

Example

# List objects information.
objects = minio.list_objects('foo')
for object in objects:
    print(object)

# List objects information those names starts with 'hello/'.
objects = minio.list_objects('foo', prefix='hello/')
for object in objects:
    print(object)

# List objects information recursively.
objects = minio.list_objects('foo', recursive=True)
for object in objects:
    print(object)

# List objects information recursively those names starts with
# 'hello/'.
objects = minio.list_objects(
    'foo', prefix='hello/', recursive=True,
)
for object in objects:
    print(object)

get_bucket_policy(bucket_name)

Get bucket policy configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Return Value

Param
Bucket policy configuration as JSON string.

Example

config = minio.get_bucket_policy("my-bucketname")

set_bucket_policy(bucket_name, policy)

Set bucket policy configuration to a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.
Policy str Bucket policy configuration as JSON string.

Example

minio.get_bucket_policy("my-bucketname", config)

delete_bucket_policy(bucket_name)

Delete bucket policy configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

minio.delete_bucket_policy("my-bucketname")

get_bucket_notification(bucket_name)

Get notification configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Return Value

Param
Notification configuration as dict.

Example

config = minio.get_bucket_notification("my-bucketname")

set_bucket_notification(bucket_name, notification)

Set notification configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.
notification dict Non-empty dictionary with the structure specified below.

The notification argument has the following structure:

At least one of the above items needs to be specified in the
notification argument.

The "service configuration item" alluded to above has the following structure:

Example

config = {
    'QueueConfigurations': [
        {
            'Id': '1',
            'Arn': 'arn1',
            'Events': ['s3:ObjectCreated:*'],
            'Filter': {
                'Key': {
                    'FilterRules': [
                        {
                            'Name': 'prefix',
                            'Value': 'abc'
                        }
                    ]
                }
            }
        }
    ],
    'TopicConfigurations': [
        {
            'Arn': 'arn2',
            'Events': ['s3:ObjectCreated:*'],
            'Filter': {
                'Key': {
                    'FilterRules': [
                        {
                            'Name': 'suffix',
                            'Value': '.jpg'
                        }
                    ]
                }
            }
        }
    ],
    'CloudFunctionConfigurations': [
        {
            'Arn': 'arn3',
            'Events': ['s3:ObjectRemoved:*'],
            'Filter': {
                'Key': {
                    'FilterRules': [
                        {
                            'Name': 'suffix',
                            'Value': '.jpg'
                        }
                    ]
                }
            }
        }
    ]
}

minio.set_bucket_notification("my-bucketname", config)

remove_all_bucket_notification(bucket_name)

Remove notification configuration of a bucket. On success, S3 service stops notification of events previously set of the bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

minio.remove_all_bucket_notification("my-bucketname")

listen_bucket_notification(bucket_name, prefix='', suffix='', events=('s3:ObjectCreated:', 's3:ObjectRemoved:', 's3:ObjectAccessed:*'))

Listen events of object prefix and suffix of a bucket. Caller should iterate returned iterator to read new events.

Parameters

Param Type Description
bucket_name str Name of the bucket.
prefix str Listen events of object starts with prefix.
suffix str Listen events of object ends with suffix.
events list Events to listen.
iter = minio.listen_bucket_notification(
    "my-bucketname",
    events=('s3:ObjectCreated:*', 's3:ObjectAccessed:*'),
)
for events in iter:
    print(events)

get_bucket_encryption(bucket_name)

Get encryption configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Return Value

Param
Encryption configuration as dict.

Example

config = minio.get_bucket_encryption("my-bucketname")

put_bucket_encryption(bucket_name, encryption_configuration)

Set encryption configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.
enc_config dict Encryption configuration as dictionary to be set.

Example

# Sample default encryption configuration
config = {
    'ServerSideEncryptionConfiguration':{
        'Rule': [
            {'ApplyServerSideEncryptionByDefault': {'SSEAlgorithm': 'AES256'}}
        ]
    }
}

minio.put_bucket_encryption("my-bucketname", config)

delete_bucket_encryption(bucket_name)

Delete encryption configuration of a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

minio.delete_bucket_encryption("my-bucketname")

enable_bucket_versioning(bucket_name)

Enable object versioning feature in a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

minio.enable_bucket_versioning("my-bucketname")

disable_bucket_versioning(bucket_name)

Disable object versioning feature in a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.

Example

minio.disable_bucket_versioning("my-bucketname")

3. Object operations

get_object(bucket_name, object_name, offset=0, length=0, request_headers=None, sse=None, version_id=None, extra_query_params=None)

Gets data from offset to length of an object. Returned response should be closed after use to release network resources. To reuse the connection, its required to call response.release_conn() explicitly.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
offset int Start byte position of object data.
length int Number of bytes of object data from offset.
request_headers dict Any additional headers to be added with GET request.
sse SseCustomerKey Server-side encryption customer key.
version_id str Version-ID of the object.
extra_query_params dict Extra query parameters for advanced usage.

Return Value

Return
urllib3.response.HTTPResponse object.

Example

// Get entire object data.
 try:
    response = minio.get_object('foo', 'bar')
    // Read data from response.
finally:
    response.close()
    response.release_conn()

// Get object data for offset/length.
try:
    response = minio.get_object('foo', 'bar', 2, 4)
    // Read data from response.
finally:
    response.close()
    response.release_conn()

select_object_content(bucket_name, object_name, opts)

Select content of an object by SQL expression.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
opts SelectObjectOptions Options for select object.

Return Value

Return
A reader contains requested records and progress information as SelectObjectReader

Example

options = SelectObjectOptions(
    expression=" select * from s3object",
    input_serialization=InputSerialization(
        compression_type="NONE",
        csv=CSVInput(file_header_info="USE",
                     record_delimiter="\n",
                     field_delimiter=",",
                     quote_character='"',
                     quote_escape_character='"',
                     comments="#",
                     allow_quoted_record_delimiter="FALSE",
                     ),
        ),

    output_serialization=OutputSerialization(
        csv=CSVOutput(quote_fields="ASNEEDED",
                      record_delimiter="\n",
                      field_delimiter=",",
                      quote_character='"',
                      quote_escape_character='"',)
                      ),
    request_progress=RequestProgress(
        enabled="FALSE"
        )
    )

data = client.select_object_content('my-bucket', 'my-object', options)
# Get the records
with open('my-record-file', 'w') as record_data:
    for d in data.stream(10*1024):
        record_data.write(d)

    # Get the stats
    print(data.stats())

fget_object(bucket_name, object_name, file_path, request_headers=None, sse=None, version_id=None, extra_query_params=None)

Downloads data of an object to file.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
file_path str Name of file to upload.
request_headers dict Any additional headers to be added with GET request.
sse SseCustomerKey Server-side encryption customer key.
version_id str Version-ID of the object.
extra_query_params dict Extra query parameters for advanced usage.

Return Value

Return
Object information as Object

Example

minio.fget_object('foo', 'bar', 'localfile')
minio.fget_object(
    'foo', 'bar', 'localfile', version_id='VERSION-ID',
)

copy_object(bucket_name, object_name, object_source, conditions=None, source_sse=None, sse=None, metadata=None)

Create an object by server-side copying data from another object. In this API maximum supported source object size is 5GiB.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
object_source str Source object to be copied.
conditions CopyConditions Collection of supported CopyObject conditions.
source_sse SseCustomerKey Server-side encryption customer key of source object.
sse Sse Server-side encryption of destination object.
metadata dict Any user-defined metadata to be copied along with destination object.

Return Value

Return
CopyObjectResult

Example

import time
from datetime import datetime
from minio import CopyConditions

minio.copy_object(
    "my-bucketname",
    "my-objectname",
    "my-source-bucketname/my-source-bucketname",
)

minio.copy_object(
    "my-bucketname",
    "my-objectname",
    "my-source-bucketname/my-source-bucketname"
    "?versionId=b6602757-7c9c-449b-937f-fed504d04c94",
)

copy_conditions = CopyConditions()
# Set modified condition, copy object modified since 2014 April.
t = (2014, 4, 0, 0, 0, 0, 0, 0, 0)
mod_since = datetime.utcfromtimestamp(time.mktime(t))
copy_conditions.set_modified_since(mod_since)

# Set unmodified condition, copy object unmodified since 2014 April.
copy_conditions.set_unmodified_since(mod_since)

# Set matching ETag condition, copy object which matches the following ETag.
copy_conditions.set_match_etag("31624deb84149d2f8ef9c385918b653a")

# Set matching ETag except condition, copy object which does not match the following ETag.
copy_conditions.set_match_etag_except("31624deb84149d2f8ef9c385918b653a")

# Set metadata, which will be copied along with the destination object.
metadata = {"test-key": "test-data"}

result = minioClient.copy_object(
    "mybucket",
    "myobject",
    "/my-sourcebucketname/my-sourceobjectname",
    copy_conditions,metadata=metadata,
)
print(result)

put_object(bucket_name, object_name, data, length, content_type='application/octet-stream', metadata=None, sse=None, progress=None, part_size=DEFAULT_PART_SIZE)

Uploads data from a stream to an object in a bucket.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
data io.RawIOBase Contains object data.
content_type str Content type of the object.
metadata dict Any additional metadata to be uploaded along with your PUT request.
sse Sse Server-side encryption.
progress threading A progress object.
part_size int Multipart part size.

Return Value

Return
etag and version ID if available.

Example

file_stat = os.stat('hello.txt')
with open('hello.txt', 'rb') as data:
    minio.put_object(
        'foo', 'bar', data, file_stat.st_size, 'text/plain',
    )

fput_object(bucket_name, object_name, file_path, content_type='application/octet-stream', metadata=None, sse=None, progress=None, part_size=DEFAULT_PART_SIZE)

Uploads data from a file to an object in a bucket.

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
file_path str Name of file to upload.
content_type str Content type of the object.
metadata dict Any additional metadata to be uploaded along with your PUT request.
sse Sse Server-side encryption.
progress threading A progress object.
part_size int Multipart part size.

Return Value

Return
etag and version ID if available.

Example

minio.fput_object('foo', 'bar', 'filepath', 'text/plain')

stat_object(bucket_name, object_name, sse=None, version_id=None, extra_query_params=None)

Get object information and metadata of an object.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
sse SseCustomerKey Server-side encryption customer key.
version_id str Version ID of the object.
extra_query_params dict Extra query parameters for advanced usage.

Return Value

Return
Object information as Object

Example

stat = minio.stat_object("my-bucketname", "my-objectname")

remove_object(bucket_name, object_name, version_id=None)

Remove an object.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
version_id str Version ID of the object.

Example

minio.remove_object("my-bucketname", "my-objectname")
minio.remove_object(
    "my-bucketname",
    "my-objectname",
    version_id="13f88b18-8dcd-4c83-88f2-8631fdb6250c",
)

remove_objects(bucket_name, objects_iter)

Remove multiple objects.

Parameters

Param Type Description
bucket_name str Name of the bucket.
objects_iter list An iterable type python object providing object names for deletion.

Return Value

Return
An iterator contains MultiDeleteError

Example

minio.remove_objects(
    "my-bucketname",
    [
        "my-objectname1",
        "my-objectname2",
        ("my-objectname3", "13f88b18-8dcd-4c83-88f2-8631fdb6250c"),
    ],
)

4. Presigned operations

presigned_get_object(bucket_name, object_name, expires=timedelta(days=7), response_headers=None, request_date=None, version_id=None, extra_query_params=None)

Get presigned URL of an object to download its data with expiry time and custom request parameters.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
expires datetime.timedelta Expiry in seconds; defaults to 7 days.
response_headers dict Optional response_headers argument to specify response fields like date, size, type of file, data about server, etc.
request_date datetime.datetime Optional request_date argument to specify a different request date. Default is current date.
version_id str Version ID of the object.
extra_query_params dict Extra query parameters for advanced usage.

Return Value

Return
URL string

Example

# Get presigned URL string to download 'my-objectname' in
# 'my-bucketname' with default expiry.
url = minio.presigned_get_object("my-bucketname", "my-objectname")
print(url)

# Get presigned URL string to download 'my-objectname' in
# 'my-bucketname' with two hours expiry.
url = minio.presigned_get_object(
    "my-bucketname", "my-objectname", expires=timedelta(hours=2),
)
print(url)

presigned_put_object(bucket_name, object_name, expires=timedelta(days=7))

Get presigned URL of an object to upload data with expiry time and custom request parameters.

Parameters

Param Type Description
bucket_name str Name of the bucket.
object_name str Object name in the bucket.
expires datetime.timedelta Expiry in seconds; defaults to 7 days.

Return Value

Return
URL string

Example

# Get presigned URL string to upload data to 'my-objectname' in
# 'my-bucketname' with default expiry.
url = minio.presigned_put_object("my-bucketname", "my-objectname")
print(url)

# Get presigned URL string to upload data to 'my-objectname' in
# 'my-bucketname' with two hours expiry.
url = minio.presigned_put_object(
    "my-bucketname", "my-objectname", expires=timedelta(hours=2),
)
print(url)

presigned_post_policy(post_policy)

Get form-data of PostPolicy of an object to upload its data using POST method.

Parameters

Param Type Description
post_policy PostPolicy Post policy.

Return Value

Return
Form-data containing dict

Example

Create policy:

post_policy = PostPolicy()
post_policy.set_bucket_name('bucket_name')

# set object prefix for object upload.
post_policy.set_key_startswith('objectPrefix/')

# set expiry to 10 days.
expires_date = datetime.utcnow()+timedelta(days=10)
post_policy.set_expires(expires_date)

# set content length for incoming uploads.
post_policy.set_content_length_range(10, 1024)

# set content-type to allow only text.
post_policy.set_content_type('text/plain')

form_data = presigned_post_policy(post_policy)
print(form_data)

5. Explore Further