🎉Black Friday deal: 40% off all lifetime licenses with code BF2026

MinIO on macOS: Local S3 Bucket Setup with BucketMate

Short answer: install the MinIO client on Mac with brew install minio/stable/mc, and the MinIO server with brew install minio/stable/minio. Do not run brew install mc - that installs Midnight Commander, a different tool that also uses the mc command.

2026 caveat: MinIO community edition is archived and no longer maintained. These brew commands still install the last pre-built release for local development, but Homebrew has deprecated both formulas and will disable minio on 2027-02-17. See MinIO status in 2026 for what changed and the alternatives.

MinIO is a fast way to spin up an S3-compatible object store on macOS so you can work offline, test APIs without touching production, and keep a local cache of critical data. Pair it with a smart sync routine and you gain a hybrid workflow where your Mac mirrors a cloud bucket while BucketMate gives you a native UI for day-to-day file ops.

Quick start: install the MinIO server and the mc client with Homebrew, start a server, and create a bucket:

brew install minio/stable/minio minio/stable/mc
minio server ~/minio-data --console-address ":9001"
mc alias set local http://127.0.0.1:9000 minioadmin minioadmin
mc mb local/my-bucket

The S3 API runs on http://127.0.0.1:9000 and the web console on http://127.0.0.1:9001. The rest of this guide covers a safer setup with your own credentials, connecting a GUI, and syncing with a cloud bucket.

Heads-up: in 2025 MinIO stripped most admin features out of the community web Console, leaving a basic object browser, and the community repo was archived in April 2026. Use mc for admin tasks and a desktop S3 GUI like BucketMate for daily browsing, uploads, and previews.

MinIO status in 2026

MinIO community edition is no longer an actively maintained product. If you use it on a Mac today, this is what you are running:

  • Archived: the minio/minio repository went into maintenance mode in December 2025 and was archived (read-only) in April 2026. The minio/mc client repository is archived too.
  • Source only: MinIO stopped publishing pre-built community binaries and Docker images in October 2025. Existing binaries still run but will not get updates, including security fixes. New builds come from source with go install github.com/minio/minio@latest.
  • No official Docker image: minio/minio on Docker Hub and quay.io/minio/minio no longer exist, so docker pull minio/minio fails. Use cgr.dev/chainguard/minio (built from MinIO source) or pgsty/minio (a maintained fork that works as a drop-in replacement). See which MinIO Docker image to use in 2026.
  • Homebrew deprecated: the Homebrew core minio formula is deprecated and will be disabled on 2027-02-17. minio-mc is deprecated with a disable date of 2027-07-17. The minio/stable tap still installs, but it is pinned to an older release.
  • Console is an object browser: the community Console lost its admin UI in 2025. Users, policies, and access keys are managed with mc admin.
  • Supported product: MinIO now ships AIStor, with a free standalone edition and a commercially supported enterprise edition. See the minio/minio README for links.

For a throwaway local S3 endpoint on your Mac, the archived community build still does the job. For anything long-lived, build from source and pin the version, move to AIStor Free, or pick another S3-compatible server. BucketMate connects to all of them the same way.

Why pair MinIO with a Mac and BucketMate

  • Offline-first reliability: Keep product demos, build artifacts, or AI models available without an internet connection while still syncing changes back to AWS S3, Cloudflare R2, Wasabi, or Backblaze B2.
  • Production-safe testing: Point staging apps or integration tests at the local endpoint to validate IAM policies, lifecycle rules, and SDK calls before deploying.
  • Friendly management: BucketMate’s native macOS app lists objects, previews files, and lets you drag and drop between local MinIO and remote cloud providers without scripts.

1. Install MinIO client (mc) and server with Homebrew

MinIO ships as two single binaries: minio (the server) and mc (the MinIO client). Install them from the official MinIO tap. Both are frozen at their last pre-built release, which is fine for local development.

Install the MinIO client (mc) with brew

brew install minio/stable/mc
mc --version

If you only need to talk to a remote MinIO, AWS S3, or R2 endpoint, the client is all you need. Homebrew core also ships it as brew install minio-mc.

brew install mc installs Midnight Commander, not the MinIO client. If you already have Midnight Commander, the two mc binaries conflict - uninstall one or call the MinIO client by its full path.

Install the MinIO server with brew

brew install minio/stable/minio
minio --version

Homebrew core also has brew install minio. Both upstream repositories are archived, so Homebrew marks these formulas as deprecated - they still install and run fine for local development, but do not expect new releases. Homebrew will disable minio on 2027-02-17 and minio-mc on 2027-07-17, after which brew install refuses them.

Deprecation note: if brew install minio stops working for you, build the server from source instead. With Go 1.24 or later, run go install github.com/minio/minio@latest and go install github.com/minio/mc@latest, then make sure $(go env GOPATH)/bin is on your PATH. Either path gives you the same commands used throughout this tutorial.

2. Create a dedicated data directory

Choose a persistent location for object data so the MinIO process can restart without losing state. The examples below assume ~/minio-data.

mkdir -p ~/minio-data

You can target an external SSD or network volume if you want more space or redundancy.

3. Launch MinIO on macOS

Start MinIO with explicit addresses so you know which ports to allow through the firewall.

minio server --address :9000 --console-address :9001 ~/minio-data

Open http://127.0.0.1:9001 in a browser to reach the web console. The default credentials are minioadmin for both username and password. Change them immediately in production-like setups. Recent community builds only show an object browser there - users, policies, and access keys are managed with mc admin.

If you need TLS, generate certificates under ~/minio-certs and restart MinIO with --certs-dir ~/minio-certs. BucketMate will trust the certificate as long as it matches the hostname you configure inside the app.

4. Configure the MinIO client (mc)

The mc CLI mirrors the AWS S3 CLI but works across any S3-compatible target. Set up an alias for your local server, then create a bucket dedicated to offline work.

mc alias set localminio http://127.0.0.1:9000 minioadmin minioadmin
mc mb localminio/offline-projects

Keep the alias names simple because they appear throughout mirror commands and scripts.

5. Connect BucketMate to your local MinIO

  1. Launch BucketMate on macOS.
  2. Click Add connection and choose MinIO as the provider (or Other).
  3. Enter the endpoint http://127.0.0.1:9000 (or https:// if you enabled TLS).
  4. Supply the access key, secret key, and bucket you created above.
  5. Tap Test connection and then Save to add it to your sidebar.
BucketMate Add Connection dialog with the provider list open, including MinIO and Other for custom S3-compatible endpoints
Choose MinIO (or Other) in the provider list, then enter your local endpoint.

BucketMate now treats your MinIO server like any other cloud bucket. Drag a folder into the window to upload objects, rename files inline, and preview media without reaching for the CLI.

BucketMate on macOS with a local MinIO dev-sandbox bucket open, an uploads folder expanded and an image preview, next to Cloudflare R2 and AWS S3 connections in the sidebar
Local MinIO sits next to R2 and AWS in the same sidebar.

6. Keep MinIO in sync with a cloud bucket

Hybrid backup is where MinIO shines. Mirroring lets you operate locally while keeping a canonical copy in cloud storage.

A. Prep cloud credentials

Create a second alias that points at your provider of choice. Replace the endpoint and credentials with the values for AWS S3, Cloudflare R2, Wasabi, or Backblaze B2.

mc alias set cloudbackup https://s3.amazonaws.com AKIA... wJalrXUtnFEMI...

Use environment variables or a password manager to store secrets when you move from demos to production.

B. Run one-time seeding

Push your existing offline folder into MinIO so both locations start with the same data.

mc mirror ~/Projects/offline-cache localminio/offline-projects --overwrite --watch

The --watch flag keeps the process running, so new files or edits propagate in near real-time.

C. Mirror to the cloud provider

Once your local bucket is up-to-date, mirror it to the remote alias.

mc mirror localminio/offline-projects cloudbackup/prod-backups --overwrite

Schedule the command with launchctl, cron, or a CI runner depending on how frequently you want to back up.

7. Generate tailor-made commands

Every team tweaks paths, aliases, and TLS preferences. Use the interactive planner below to produce commands that match your setup exactly, then copy them into your shell scripts or runbooks.

Endpoint
http://127.0.0.1:9000
Mirror direction
Generated commands
minio server --address :9000 --console-address :9001 ~/minio-data
mc alias set localminio http://127.0.0.1:9000 minioadmin minioadmin
mc mb localminio/offline-projects
mc mirror ~/Projects/offline-cache localminio/offline-projects --overwrite --watch
mc mirror localminio/offline-projects cloudbackup/prod-backups --overwrite

8. Automate checks and lifecycle policies

  • Health checks: Use mc admin info localminio inside a monitoring script to verify drive space and uptime. Pair it with a simple curl against the /minio/health/ready endpoint for readiness probes.
  • Lifecycle rules: Create bucket policies that expire build artifacts or move stale releases into Glacier or R2 object lifecycle equivalents.
  • Integrity scans: Schedule periodic mc diff localminio/offline-projects cloudbackup/prod-backups runs and alert on mismatches so you can react before gaps grow.

9. Troubleshooting tips for macOS

  • Port conflicts: If 9000 or 9001 are taken, adjust the ports in the server command and within BucketMate. The planner above regenerates commands instantly when you change the numbers.
  • Permissions: When storing data on external drives, grant Full Disk Access to the terminal and BucketMate so they can read and write without prompts.
  • Firewall prompts: Approve the first-run firewall dialog so incoming connections on the chosen port stay open. For TLS, add the certificate to the macOS Keychain and mark it as trusted.

10. Keep your hybrid stack organized

  • Label buckets clearly inside BucketMate so teammates know which connection is local versus cloud.
  • Use consistent prefixes (for example team-name/environment/data-type/) so lifecycle rules and sync filters stay predictable.
  • Export your BucketMate connections as encrypted backups to share with trusted teammates or to rebuild a machine quickly.

FAQ

How do I install the MinIO client on Mac with brew?

Run brew install minio/stable/mc, then mc --version to confirm. brew install minio-mc from Homebrew core works too. Do not use brew install mc, which installs Midnight Commander.

How do I install the MinIO server with brew?

Run brew install minio/stable/minio (or brew install minio), then start it with minio server ~/minio-data --console-address ":9001". The formula is deprecated and will be disabled on 2027-02-17. After that, use go install github.com/minio/minio@latest.

Is MinIO still maintained in 2026?

No. The community edition was archived in April 2026 and is distributed as source only. The supported product is MinIO AIStor, which has a free edition. See MinIO status in 2026.

Why does brew install mc give me Midnight Commander?

In Homebrew, mc is an alias for the Midnight Commander file manager. The MinIO client lives in the minio/stable tap or under the minio-mc formula name.

Is there a GUI for MinIO on Mac now that the Console lost its admin features?

Yes. Any S3-compatible desktop client works with MinIO. BucketMate connects to local or remote MinIO next to AWS S3 and Cloudflare R2, with drag-and-drop uploads, previews, and share links. Keep mc admin for users and policies.

What are the default MinIO credentials?

minioadmin / minioadmin. Set MINIO_ROOT_USER and MINIO_ROOT_PASSWORD before starting the server for anything beyond a throwaway test.

Next steps

You now have a local S3-compatible bucket on macOS, synced to the cloud, and visible inside BucketMate. Continue exploring hybrid storage patterns with the Cloudflare R2 setup guide or compare providers in the R2 vs S3 breakdown. For connection fields and MinIO-specific errors in BucketMate, see the Connect MinIO docs or the MinIO GUI client page.