minio/minio

Getting started

This page covers building MinIO from source, running it locally, and connecting to it. It pulls together the practical bits scattered across README.md, CONTRIBUTING.md, Makefile, and the various docs/* folders.

Prerequisites

Go 1.24+. go.mod declares go 1.24.0 and the toolchain pins to go1.24.8. Earlier versions will not compile.
Make (tested with GNU make).
A POSIX shell, git, curl. Many make test-* targets shell out to scripts under buildscripts/ and docs/.
For the race-instrumented build (make install-race) you also need a working C toolchain because CGO_ENABLED=1 is set.
For Docker workflows: any Docker engine that understands Dockerfile syntax.

Build the binary

git clone https://github.com/minio/minio
cd minio
make build

make build runs buildscripts/checkdeps.sh first to verify the Go toolchain, then buildscripts/gen-ldflags.go to compute the version stamp, then a go build -tags kqueue -trimpath invocation that drops the minio binary in the repo root. To install into $GOPATH/bin, run make install. To cross-compile for many platforms, run make crosscompile (see buildscripts/cross-compile.sh).

To install the latest released module without cloning:

go install github.com/minio/minio@latest

Run a single-node server

./minio server /tmp/minio

That starts MinIO with default root credentials minioadmin:minioadmin listening on :9000 and exposing the embedded console on a random port (set --console-address :9001 to pin it). See cmd/server-main.go for every flag and matching environment variable (MINIO_ADDRESS, MINIO_CONSOLE_ADDRESS, MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, ...).

Open http://127.0.0.1:9000 in a browser to use the embedded MinIO Console (provided by the github.com/minio/console dependency).

Run a distributed cluster

The classic example from cmd/server-main.go's help text:

./minio server http://node{1...4}.example.com/mnt/export{1...4}

You must run the same command on every node, with the same set of endpoints. The ellipsis pattern {1...N} is expanded by cmd/endpoint-ellipses.go into one erasure set per group of drives. Server pools are separated with a space:

./minio server http://node{1...16}.example.com/mnt/export{1...32} \
              http://node{17...64}.example.com/mnt/export{1...64}

For more topology guidance see docs/distributed/ and docs/multi-tenancy/.

Connect with `mc`

mc is the official MinIO Client. It is the easiest way to drive the server.

mc alias set local http://localhost:9000 minioadmin minioadmin
mc admin info local
mc mb local/data
mc cp ~/Downloads/myfile local/data/
mc ls local/data/

mc admin is also the entry point for IAM, replication, lifecycle, KMS, and healing administration. The HTTP routes mc admin calls live under /minio/admin/v3 and are defined in cmd/admin-router.go.

Run unit tests

make test

make test chains verifiers (lint + check-gen), build, then go test -v -tags kqueue,dev ./... with MINIO_API_REQUESTS_MAX=10000 and CGO_ENABLED=0. The build tags kqueue and dev enable the cross-platform poller and developer-only assertions.

For race-instrumented unit tests:

make test-race    # invokes buildscripts/race.sh

Run integration tests

The Makefile defines many shell-driven integration suites. Each one boots one or more minio servers, drives mc against them, and asserts behaviour. Useful entry points:

Target	What it covers
`make test-iam`	IAM with external IDP and etcd backends
`make test-replication`	Two- and three-site bucket replication
`make test-site-replication-*`	Cluster-to-cluster replication with LDAP / OIDC / native IDP
`make test-decom`	Pool decommission flow (with and without encryption)
`make test-versioning`	Bucket versioning end-to-end
`make test-ilm`	Lifecycle expiration, transition, replication interplay
`make verify`, `make verify-healing`	Multi-mode healing and replacing-disks scenarios

The shell harness scripts live in docs/distributed/, docs/bucket/replication/, docs/site-replication/, and buildscripts/.

Build and run a Docker image

make build         # produce ./minio
docker build -t myminio:minio .
docker run -p 9000:9000 -p 9001:9001 myminio:minio server /tmp/minio --console-address :9001

Variants:

Dockerfile — community build (consumes the local ./minio binary).
Dockerfile.release and Dockerfile.release.old_cpu — official multi-arch images.
Dockerfile.hotfix — used by the make hotfix Makefile target to ship one-off patched binaries.
Dockerfile.scratch — minimal "from scratch" image for embedding.

Helm and Kubernetes

helm install --namespace minio --create-namespace minio ./helm/minio

The chart is community-maintained; see helm/minio/ for values and helm-releases/ for the historical chart bundles. For production Kubernetes, README.md recommends the MinIO Operator instead of the bare chart.