minio-go

minio-go is the official Go SDK for MinIO, providing a single client API that works against MinIO, AWS S3, and any other S3-compatible object storage backend. It wraps the full S3 REST API surface — bucket and object CRUD, multipart and streaming uploads, presigned URLs, server-side encryption, object locking, lifecycle and replication policies, bucket notifications, and MinIO-specific extensions like SELECT-object-content and object annotations — behind a single Client type built around context.Context.

The library is designed for production use at scale: request signing (V2 and V4), automatic retries with jittered exponential backoff, health-check driven failover, connection pooling via a shared http.Transport, and streaming I/O throughout so large objects never need to be buffered fully in memory. A lower-level Core type is also exposed for callers who need direct access to multipart upload primitives instead of the higher-level streaming helpers.

As the reference Go client for the MinIO ecosystem, it is the natural dependency for any Go service that reads or writes object storage — file uploads, backups, data lake ingestion, or building tools on top of MinIO/S3 directly.

What You Get

• A Client type covering the full S3 API surface: MakeBucket, ListObjects, PutObject, GetObject, CopyObject, RemoveObject(s), and dozens more, all context.Context-aware
• Streaming and multipart upload/download helpers (PutObject, FPutObject, GetObject, FGetObject) that never require buffering a whole object in memory
• Presigned URL generation (PresignedGetObject, PresignedPutObject, PresignedPostPolicy) for browser/client-side uploads and downloads without exposing credentials
• Bucket-level policy, lifecycle, encryption, versioning, tagging, notification, and replication configuration APIs
• A lower-level Core type exposing raw multipart primitives for callers building their own upload strategies
• Pluggable credential providers (pkg/credentials) supporting static keys, IAM, STS, and chained providers, plus V2/V4 request signing

Common Use Cases

• Uploading and serving user-generated files (images, documents, media) from a Go backend to MinIO or S3
• Building backup and archival pipelines that write to any S3-compatible object store
• Generating presigned upload/download URLs so browsers or mobile clients can transfer directly to storage without proxying through the API server
• Object storage as a data lake sink — writing and listing large volumes of objects for downstream analytics
• Implementing self-hosted, S3-compatible file storage for applications that need to avoid vendor lock-in to AWS

Under The Hood

Architecture The library centers on a single Client struct (api.go) constructed via minio.New(endpoint, *Options), holding the parsed endpoint, credential provider, HTTP client/transport, region and bucket-location caches, and signing configuration. Every S3 operation is a method on Client that builds a request through shared internal helpers, applies V2/V4 signing from pkg/signer, and executes it through a pluggable http.RoundTripper, with retry.go wrapping calls in jittered exponential backoff and healthcheck state tracking endpoint availability. A separate Core type (core.go) re-exposes the same transport but with raw multipart primitives (PutObjectPart, ListMultipartUploads) for callers who want to manage multipart uploads themselves rather than use the higher-level streaming helpers — the two share the same underlying Client, so Core is additive rather than a parallel implementation. Domain concerns are split into single-purpose files by API area (api-bucket-policy.go, api-object-lock.go, api-put-object-multipart.go, etc.) rather than one large client file, and supporting concerns (credentials, signing, S3 utilities, an LRU-style key/value cache) live in dedicated pkg/ subpackages so they can be imported independently. An optional RDMA transport (rdma.go, built only with -tags=rdma) dispatches PutObject/GetObject to a native libminiocpp.so when the caller supplies an RDMA buffer, with a no-op stub (rdma_stub.go) satisfying the same struct shape in normal builds.

Tech Stack Written in Go (module targets Go 1.25) with a deliberately small dependency footprint: github.com/minio/md5-simd and github.com/minio/crc64nvme/klauspost/crc32 for accelerated checksums, google/uuid and rs/xid for identifiers, dustin/go-humanize for human-readable sizes, tinylib/msgp and go.yaml.in/yaml for serialization, and golang.org/x/net/golang.org/x/crypto for transport and TLS extras — no web framework or ORM, since this is a pure client library. Builds and releases run through a Makefile and GitHub Actions across Linux, Windows, and an ARM/AMD64 RDMA-tagged build that links against a companion minio-cpp native library and vcpkg-provisioned dependencies.

Code Quality Testing is extensive: 25 _test.go files alongside their implementation files (unit tests colocated per API area) plus a large functional_tests.go integration suite that exercises the client against a live MinIO/S3 endpoint. Errors are handled explicitly and typed — s3-error.go defines named S3 error-code constants (NoSuchBucket, AccessDenied, etc.) that callers can compare against rather than parsing strings. Linting is enforced via golangci-lint (pinned as a Go tool dependency) with a broad rule set (gocritic, revive, staticcheck, unused, ineffassign), and CI runs a dedicated govulncheck workflow in addition to standard build/test workflows for Linux, Windows, and the RDMA variant.

What Makes It Unique Beyond standard S3 compatibility, the library exposes several MinIO-specific extensions not found in the stock AWS SDK: ListenBucketNotification/ListenNotification for real-time bucket event streams, SelectObjectContent for server-side SQL-like filtering of object contents, object annotation APIs, and an experimental RDMA transport path for high-throughput transfers to MinIO clusters over RDMA-capable networks. Combined with its dual Client/Core design, it serves both simple upload/download use cases and advanced callers who need low-level multipart control, while remaining a single dependency that works identically against MinIO or AWS S3.