MinIO Client (mc)

MinIO Client (mc) cheatsheet — manage S3-compatible storage. mc ls, mc cp, mc mb, mc mirror, mc alias set. Works with MinIO, AWS S3, GCS. Full mc reference.

7 min read

What it is

The MinIO Client (mc) is a command-line tool for interacting with MinIO object storage and other S3-compatible object storage services, allowing you to manage buckets, objects, and perform various operations like uploading, downloading, and syncing.

Installation

Linux

wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

macOS

wget https://dl.min.io/client/mc/release/darwin-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

Windows

Download the appropriate mc.exe from the MinIO releases page and place it in your system’s PATH.

Core Concepts

Aliases: mc uses aliases to represent configured MinIO or S3 endpoints. You define an alias once, and then refer to it by its alias name (e.g., myS3, minio-prod). This simplifies commands by avoiding the need to repeatedly type endpoint URLs, access keys, and secret keys.
Buckets: Similar to directories in a file system, buckets are containers for objects in object storage.
Objects: These are the actual data files stored within buckets. Objects have a key (their name/path within the bucket) and associated metadata.

Commands / Usage

Configuration and Aliases

Alias a new MinIO or S3 endpoint:
```
mc alias set myS3 http://192.168.1.100:9000 minioadmin minioadmin
```
Sets up an alias named myS3 for a MinIO server at http://192.168.1.100:9000 using minioadmin as both access and secret key.
List configured aliases:
```
mc alias list
```
Displays all currently configured aliases and their associated endpoints.
Remove an alias:
```
mc alias remove myS3
```
Deletes the alias myS3 from your configuration.

Bucket Operations

Create a bucket:
```
mc mb myS3/my-new-bucket
```
Creates a new bucket named my-new-bucket on the MinIO instance aliased as myS3.
List buckets:
```
mc ls myS3
```
Lists all buckets within the MinIO instance aliased as myS3.
Remove a bucket (must be empty):
```
mc rb myS3/my-old-bucket
```
Removes the bucket my-old-bucket from the myS3 instance. This command will fail if the bucket is not empty.
Remove a bucket and its contents recursively:
```
mc rb --recursive myS3/my-old-bucket
```
Forcefully removes the bucket my-old-bucket and all objects within it from the myS3 instance. Use with caution.

Object Operations

List objects in a bucket:
```
mc ls myS3/my-bucket
```
Lists all objects and subdirectories within the my-bucket on the myS3 instance.
List objects in a bucket with size and date:
```
mc ls --human-readable myS3/my-bucket
```
Lists objects with human-readable sizes and modification dates.
Upload a local file to a bucket:
```
mc cp /path/to/local/file.txt myS3/my-bucket/
```
Copies file.txt from your local filesystem to the root of my-bucket on myS3.
Upload a local file with a different name in the bucket:
```
mc cp /path/to/local/document.pdf myS3/my-bucket/new_document_name.pdf
```
Uploads document.pdf and renames it to new_document_name.pdf in my-bucket.
Upload a local directory recursively:
```
mc cp --recursive /path/to/local/folder myS3/my-bucket/
```
Copies the entire folder and its contents into my-bucket. The folder itself will be created as a prefix if it doesn’t exist in the bucket.
Download an object from a bucket:
```
mc cp myS3/my-bucket/remote_file.jpg /path/to/local/directory/
```
Downloads remote_file.jpg from myS3/my-bucket/ to your local /path/to/local/directory/.
Download an object and rename it locally:
```
mc cp myS3/my-bucket/remote_image.png /path/to/local/directory/local_image.png
```
Downloads remote_image.png and saves it as local_image.png.
Download an entire bucket recursively:
```
mc cp --recursive myS3/my-bucket /path/to/local/destination/
```
Downloads the entire my-bucket and its contents to /path/to/local/destination/.
Mirror a local directory to a bucket:
```
mc mirror /path/to/local/source/ myS3/my-bucket/
```
Synchronizes the local source directory with myS3/my-bucket/. Only changed or new files will be uploaded.
Mirror a bucket to a local directory:
```
mc mirror myS3/my-bucket/ /path/to/local/destination/
```
Synchronizes myS3/my-bucket/ with the local destination directory. Only changed or new files will be downloaded.
Remove an object:
```
mc rm myS3/my-bucket/file_to_delete.txt
```
Deletes file_to_delete.txt from myS3/my-bucket/.
Remove multiple objects matching a pattern:
```
mc rm --recursive myS3/my-bucket/logs/2023/
```
Recursively deletes all objects under the logs/2023/ prefix in my-bucket.
Move an object:
```
mc mv myS3/my-bucket/old_location/file.dat myS3/my-bucket/new_location/file.dat
```
Moves file.dat from old_location/ to new_location/ within the same bucket.
Copy an object between buckets or MinIO instances:
```
mc cp myS3/my-bucket/source_file.dat myS3_backup/backup-bucket/source_file.dat
```
Copies source_file.dat from myS3/my-bucket/ to myS3_backup/backup-bucket/.
Get object information (metadata):
```
mc stat myS3/my-bucket/my_object.txt
```
Displays detailed information about my_object.txt, including ETag, size, content type, and last modified date.
Presigned URL for temporary access:
```
mc share myS3/my-bucket/public_report.pdf
```
Generates a presigned URL to temporarily access public_report.pdf. The default expiry is 7 days.
Presigned URL with custom expiry:
```
mc share --expire 1h myS3/my-bucket/temporary_data.zip
```
Generates a presigned URL that is valid for 1 hour.

Sync Operations

Sync local directory to bucket:
```
mc sync /path/to/local/data myS3/my-bucket/data/
```
Synchronizes the local data directory with the data/ prefix in myS3/my-bucket/. Only changed or new files are transferred.
Sync bucket to local directory:
```
mc sync myS3/my-bucket/logs/ /path/to/local/logs/
```
Synchronizes the logs/ prefix in myS3/my-bucket/ with the local /path/to/local/logs/ directory.

Utility Commands

Get version information:
```
mc --version
```
Displays the mc client version and build information.
Display help for a command:
```
mc --help
mc mb --help
```
Shows general help or help for a specific subcommand.

Common Patterns

Download all objects from a bucket to a local directory:
```
mc cp --recursive myS3/my-bucket/* /local/download/path/
```
This is a common way to bulk download. The * acts as a wildcard to include all objects.
Upload all .log files from a local directory to a bucket:
```
mc cp --recursive /local/logs/*.log myS3/my-bucket/logs/
```
Uploads only files ending with .log from the local logs directory.

Find and delete old log files in a bucket:

mc ls --recursive --json myS3/my-bucket/logs/ | jq -r '.[] | select(.Type == "Object" and (.Name | endswith(".log")) and (.LastModified | fromdateiso8601 < (now - (7 * 86400)))) | .Name' | xargs -I {} mc rm myS3/my-bucket/logs/{}

This is a more advanced example using jq to filter objects older than 7 days and then piping to mc rm to delete them. Requires jq to be installed.

Syncing a web server’s static assets to MinIO:
```
mc mirror /var/www/html/assets/ myS3/website-bucket/assets/
```
Keeps the assets/ directory on MinIO in sync with the local web server’s assets.
Backup a bucket to another MinIO instance:
```
mc mirror myS3/production-data/ myS3-backup/backup-data/
```
Continuously mirrors data from one MinIO instance to another for backup purposes.

Gotchas

mc rb requires an empty bucket by default: If you try to remove a non-empty bucket with mc rb, it will fail. Use mc rb --recursive to force deletion of the bucket and its contents, but be extremely careful.
Path separators: MinIO and S3 use / as the object path separator, even on Windows. mc handles this correctly, but be mindful when constructing paths.
Wildcards (*) behavior: When used with mc cp or mc rm, wildcards typically operate on the local filesystem or the remote object keys depending on the direction of the operation. For example, mc cp /local/dir/* remote/bucket/ will copy files from /local/dir/ into remote/bucket/. mc cp remote/bucket/*.* /local/dir/ will copy objects from the root of remote/bucket/ that match *.* to /local/dir/.
mc mirror vs mc sync: mirror will delete local files if they are not present in the remote destination (when syncing from remote to local) or remote objects if they are not present in the local source (when syncing from local to remote). sync is generally safer and only adds/updates files.
Permissions and Credentials: Ensure your MinIO client configuration (mc alias set) uses the correct access and secret keys. Insufficient permissions will lead to Access Denied errors.
Large File Uploads: For very large files, mc automatically handles multipart uploads. However, network interruptions can cause partial uploads. Re-running mc cp or mc sync will typically resume or re-upload only the necessary parts.