Distribution

What is Distribution?

Distribution is an open source container registry — a server that stores and serves container images and other OCI artifacts over HTTP, following the OCI Distribution Specification. It’s the CNCF reference implementation (originally Docker Registry v2), written in Go and run as a single lightweight container.

What is Distribution best for?

Teams that want a simple, private registry to push and pull their own images without Docker Hub’s rate limits or per-seat pricing. It’s ideal as a plain image store, a CI/CD artifact target, or a pull-through cache that mirrors an upstream registry — where you want minimal moving parts, not a full platform.

What can Distribution do?

• Store and serve container images and OCI artifacts to any OCI-compliant client (Docker, containerd, Podman, Kubernetes)
• Run as one small Go binary or container image with minimal CPU and memory
• Back storage with the local filesystem, Amazon S3, Google Cloud Storage, or Azure Blob Storage
• Act as a pull-through cache (proxy mode) to mirror and cache images from an upstream registry
• Reclaim disk with garbage collection that deletes unreferenced blobs
• Secure access with htpasswd basic auth or delegated token authentication, usually behind a TLS-terminating proxy

Where does Distribution fall short?

• No web UI, users, or RBAC. It’s an API-only server — there’s no dashboard to browse images and no built-in user management, so you bolt on a separate UI and auth service if you need them.
• No vulnerability scanning, signing, or replication built in. Distribution is deliberately just the storage-and-transport layer; enterprise features like image scanning, RBAC projects, and cross-registry replication come from platforms built on top of it, such as Harbor.
• Deletion is a two-step chore. Removing an image marks the manifest, but disk isn’t freed until you run garbage collection — historically in read-only mode — which makes routine cleanup clunkier than a managed registry.

Is Distribution free?

Yes — Distribution is fully free and open source under the Apache-2.0 license, with no paid edition or feature gating. You only pay for the server and object storage it runs on. Every capability is in the open source project; there’s no separate commercial tier to buy.

What does Distribution replace?

Distribution is a self-hosted stand-in for hosted registries like Docker Hub, Amazon ECR, and JFrog Artifactory. It handles the core store-and-serve-images job on your own infrastructure — no pull-rate limits, no per-user billing — though it doesn’t match Artifactory’s multi-format artifact management or the scanning and access controls of the managed clouds.

FAQ

Is Distribution open source? Yes. It’s an Apache-2.0 licensed CNCF project (the documentation is CC-BY-4.0), and the code is public on GitHub. It’s the reference implementation of the OCI Distribution Specification.

Is Distribution the same as Docker Registry? Effectively yes. It began as Docker Registry v2 and was renamed Distribution when the project moved to the CNCF. The registry container image many teams run is this project.

Can I self-host Distribution for free? Yes. Run the official registry image with a storage backend (local disk, S3, GCS, or Azure Blob) and it costs nothing beyond your own hosting. Put it behind TLS and an auth layer for production.

Do I need Harbor instead? Only if you need a web UI, vulnerability scanning, RBAC, or replication. Harbor is built on top of Distribution and adds those; if you just need a private place to push and pull images, Distribution alone is enough.