go-containerregistry

go-containerregistry is Google’s Go library for working with container registries and OCI images. It defines a small set of immutable interfaces — v1.Image, v1.Layer, and v1.ImageIndex — that represent container image resources independently of where they live, whether that’s a remote registry, a local tarball, the Docker daemon, or an OCI image layout on disk. Functional mutation packages like mutate then produce new immutable views rather than modifying resources in place, which keeps the core model predictable and easy to reason about even as new image sources are added.

On top of the library, the repository ships several CLI tools built from the same primitives: crane for scripting registry operations (copy, push, pull, digest, manifest inspection) without a Docker daemon, gcrane for Google Container Registry / Artifact Registry specific workflows, and ko for building and deploying Go applications as containers without writing a Dockerfile. This combination — a composable library plus purpose-built CLIs — makes it a common dependency inside CI systems, image-building tools, and Kubernetes-ecosystem projects that need registry access without shelling out to docker.

What You Get

• Source-agnostic v1.Image/v1.Layer/v1.ImageIndex interfaces backed by remote registries, tarballs, the Docker daemon, or OCI layout directories
• A remote package implementing the OCI distribution spec directly over HTTP, including registry authentication via pluggable authn.Keychain implementations
• Functional mutate package for producing new image/layer/index views (append layers, rebase, change config) without in-place mutation
• crane CLI for scripting registry operations — copy, push, pull, digest, manifest, export — without invoking the Docker daemon
• ko for building and publishing Go binaries as OCI container images directly from source, with no Dockerfile required
• pkg/v1/cache, pkg/v1/layout, and pkg/v1/google packages for local layer caching, OCI image layout handling, and GCR/Artifact Registry specific helpers

Common Use Cases

• CI pipelines that need to push or promote container images to a registry without a Docker daemon available
• Building custom image-manipulation tooling (rebasing base images, injecting layers, rewriting manifests) on top of the mutate package
• Kubernetes-ecosystem tools (admission controllers, image scanners, build systems) that need to read image manifests and configs directly from a registry
• Building and deploying Go services as containers via ko, skipping Dockerfile maintenance entirely
• Copying or mirroring images between registries programmatically via crane.Copy or the crane CLI

Under The Hood

Architecture go-containerregistry is organized around a small set of immutable interfaces defined in pkg/v1 — Image, Layer, and ImageIndex (see pkg/v1/image.go) — that represent OCI resources independently of their backing medium. Concrete implementations live in sibling packages: pkg/v1/remote (registry-backed, built on pkg/v1/remote/transport for auth and structured HTTP errors), pkg/v1/tarball, pkg/v1/daemon, pkg/v1/layout, and pkg/v1/random (synthetic images for tests). Rather than mutating these resources in place, the pkg/v1/mutate package takes an existing Image/Layer/Index and returns a new one reflecting the change, which keeps every consumer’s view of a resource stable once obtained. The CLI tools in cmd/ (crane, gcrane, ko, krane) are thin cobra-based wrappers around this same library rather than a separate implementation, so library and CLI behavior stay in sync by construction. pkg/authn supplies a Keychain abstraction that both the library and CLIs use for registry credentials, with concrete keychains for Docker config, Kubernetes, and GitHub Actions.

Tech Stack The module targets Go 1.25 (toolchain 1.26) and has a deliberately small direct dependency surface for a project this size: spf13/cobra for CLI command trees, docker/cli and moby/moby client packages for daemon interop, opencontainers/image-spec and opencontainers/go-digest for OCI type definitions and content-addressable hashing, klauspost/compress for layer compression, and golang.org/x/oauth2 plus golang.org/x/sync for registry auth flows and concurrent layer operations. There’s no web framework or database — the project’s entire surface is the Go standard library’s net/http plus these OCI/registry-specific building blocks, reflecting its role as infrastructure plumbing rather than an application.

Code Quality The repository has well over a hundred _test.go files covering the core pkg/v1 types, the remote client, mutate operations, and the CLI commands, using Go’s standard testing package with table-driven test patterns (see pkg/v1/hash_test.go for a representative example). Error handling is explicit and idiomatic Go — functions return (value, error) pairs throughout rather than panicking, with sentinel and wrapped errors used for structured registry error responses in the transport package. CI (.github/workflows/) runs a dedicated test.yaml, presubmit.yaml, style.yaml, and analyze.yaml, indicating linting and static analysis run on every change in addition to unit tests, plus e2e.yaml for integration coverage against real registries.

What Makes It Unique The project’s core contribution is treating container images as a small number of composable, immutable interfaces rather than a single monolithic client — any new image source only needs to implement Image/Layer/ImageIndex, and every existing consumer (mutate, crane, ko) works with it automatically. This lets ko build container images directly from Go source without a Dockerfile or daemon, and lets crane perform registry-to-registry operations without ever materializing a full image on disk. That composability, combined with being Google’s reference Go implementation of the OCI distribution spec, has made it a foundational dependency for a wide swath of the Kubernetes and cloud-native tooling ecosystem rather than a standalone application in its own right.