MinIO Cheat Sheet

Overview

MinIO is a high-performance, S3-compatible object storage system designed for private cloud, hybrid cloud, and edge deployments. Written in Go, it delivers industry-leading throughput and can saturate modern NVMe drives. MinIO implements the full S3 API, making it a drop-in replacement for Amazon S3 in applications, tools, and frameworks that use the S3 protocol. It supports features like bucket versioning, object locking, encryption, replication, and lifecycle management.

MinIO can run as a single-node single-drive instance for development or scale to a distributed multi-node cluster with erasure coding for production workloads. It supports server-side encryption with KMS integration, identity management through LDAP/Active Directory/OIDC, and site-to-site replication for disaster recovery. MinIO is widely used for AI/ML data pipelines, data lakes, backup storage, and as a Kubernetes-native storage solution through the MinIO Operator.

Installation

Binary Installation

# Linux (single binary)
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/

# Start single-node server
minio server /data

# macOS
brew install minio/stable/minio

Docker

# Run MinIO container
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -v /data:/data \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin123 \
  quay.io/minio/minio server /data --console-address ":9001"

Install mc (MinIO Client)

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

# macOS
brew install minio/stable/mc

# Configure alias
mc alias set myminio http://localhost:9000 minioadmin minioadmin123

# Verify
mc admin info myminio

Core Commands (mc)

Command	Description
`mc ls <alias>/`	List buckets
`mc mb <alias>/<bucket>`	Create bucket
`mc rb <alias>/<bucket>`	Remove bucket
`mc cp <src> <dst>`	Copy objects
`mc mv <src> <dst>`	Move objects
`mc rm <alias>/<bucket>/<object>`	Remove object
`mc cat <alias>/<bucket>/<object>`	Display object content
`mc find <alias>/<bucket> --name "*.log"`	Find objects by pattern
`mc du <alias>/<bucket>`	Disk usage for bucket
`mc mirror <src> <dst>`	Sync directories bidirectionally
`mc stat <alias>/<bucket>/<object>`	Show object metadata

Bucket and Object Operations

# Create bucket
mc mb myminio/my-data

# Upload file
mc cp myfile.csv myminio/my-data/

# Upload directory recursively
mc cp --recursive ./logs/ myminio/my-data/logs/

# Download file
mc cp myminio/my-data/myfile.csv ./local/

# Mirror (sync) local to MinIO
mc mirror ./backups/ myminio/backup-bucket/

# Mirror with delete (exact sync)
mc mirror --remove ./backups/ myminio/backup-bucket/

# List objects recursively
mc ls --recursive myminio/my-data/

# Find large files
mc find myminio/my-data --larger 100MB

# Remove objects older than 30 days
mc rm --recursive --force --older-than 30d myminio/my-data/temp/

Administration

# Server info
mc admin info myminio

# Service restart
mc admin service restart myminio

# View server logs
mc admin logs myminio

# Check disk health
mc admin scanner myminio

# Prometheus metrics
mc admin prometheus generate myminio

# Manage users
mc admin user add myminio newuser password123
mc admin user list myminio
mc admin user disable myminio newuser

# Manage policies
mc admin policy attach myminio readwrite --user newuser
mc admin policy list myminio

Configuration

Distributed MinIO (4-Node Cluster)

# On each node (node1-node4), run:
export MINIO_ROOT_USER=admin
export MINIO_ROOT_PASSWORD=supersecret

minio server \
  http://node{1...4}/data{1...4} \
  --console-address ":9001"

Systemd Service

[Unit]
Description=MinIO Object Storage
After=network.target

[Service]
User=minio-user
Group=minio-user
EnvironmentFile=/etc/default/minio
ExecStart=/usr/local/bin/minio server $MINIO_VOLUMES $MINIO_OPTS
Restart=always
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

# /etc/default/minio
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=supersecretpassword
MINIO_VOLUMES="/data{1...4}"
MINIO_OPTS="--console-address :9001"

Bucket Policies

# Set bucket to public read
mc anonymous set download myminio/public-data

# Set custom policy
mc anonymous set-json policy.json myminio/my-data

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"AWS": ["*"]},
      "Action": ["s3:GetObject"],
      "Resource": ["arn:aws:s3:::my-data/public/*"]
    }
  ]
}

Advanced Usage

Bucket Versioning and Object Locking

# Enable versioning
mc version enable myminio/my-data

# Enable object locking (must be set at bucket creation)
mc mb --with-lock myminio/compliance-data

# Set retention policy
mc retention set --default COMPLIANCE 365d myminio/compliance-data

# List object versions
mc ls --versions myminio/my-data/myfile.csv

Site Replication

# Add site replication between two MinIO deployments
mc admin replicate add site1 site2

# Check replication status
mc admin replicate status site1

# Remove replication
mc admin replicate remove site1 site2

Encryption

# Enable auto-encryption for bucket
mc encrypt set sse-s3 myminio/secure-data

# Upload with server-side encryption
mc cp --encrypt "myminio/secure-data" myfile.csv myminio/secure-data/

Lifecycle Rules

# Add expiry rule (delete after 90 days)
mc ilm rule add --expiry-days 90 myminio/logs-bucket

# Transition to different storage tier after 30 days
mc ilm rule add --transition-days 30 --storage-class WARM myminio/my-data

# List lifecycle rules
mc ilm rule list myminio/logs-bucket

MinIO on Kubernetes

# Install MinIO Operator
kubectl krew install minio

# Initialize MinIO Operator
kubectl minio init

# Create a tenant
kubectl minio tenant create my-tenant \
  --servers 4 \
  --volumes 16 \
  --capacity 1Ti \
  --namespace minio-tenant

Troubleshooting

Issue	Solution
`Access Denied`	Verify credentials and bucket policy; check `mc admin policy`
High disk usage	Enable lifecycle rules to expire old objects; check versioning
Slow uploads	Enable multipart upload (automatic for large files); check network
Erasure coding errors	Ensure minimum number of drives are available (N/2 + 1)
Cannot access console	Verify `--console-address` flag and firewall allows the port
S3 SDK compatibility issues	Set path-style access in your S3 client configuration
TLS certificate errors	Place certs in `~/.minio/certs/` (public.crt and private.key)