← Back to Glossary

Docker Registry & Container Registry Explained (2026)

Complete guide to container registries and Docker registries: what they are, how they work, public vs private registries, OCI compliance, security best practices, and choosing the right registry for CI/CD, software distribution, and air-gapped deployments.

Container Registry & Docker Registry: Complete Guide for Software Distribution

What is a Container Registry?

A container registry is the service that stores, manages, and distributes container images and OCI-compliant artifacts. It’s the hub software teams use to publish container images out of CI/CD, distribute software to customers, and pull applications onto deployment targets, whether those targets are Kubernetes clusters, on-premises data centers, or air-gapped environments.

Registries are more than file storage. They add capabilities specific to containerized software: version control through tags, layer deduplication, authentication and access controls, vulnerability scanning, and APIs for programmatic push and pull. Registries plug directly into Docker and Kubernetes, which is why they’ve become foundational to modern cloud-native workflows.

What is a Docker Registry?

A Docker registry is a specific type of container registry designed to store and distribute Docker container images. Modern Docker registries follow the OCI (Open Container Initiative) Distribution Specification, so they work with Docker tooling and most modern container platforms. Every docker pull and docker push talks to a Docker registry.

The best-known Docker registry is Docker Hub, Docker’s public registry that hosts millions of container images from official vendors, open-source projects, and community contributors. Plenty of organizations also run private Docker registries internally, or use commercial services like those from AWS, Azure, Google Cloud, Harbor, and others. See our container registry comparison guide for a detailed look at those options.

Docker registries store images as a collection of layers (each layer representing a filesystem change) along with metadata called a manifest that describes how to assemble those layers into a runnable container image.

Container Registry vs Repository: Understanding the Difference

These terms get used interchangeably, but they actually mean different things.

Container registry:

• A service or platform that hosts multiple repositories
• Examples: Docker Hub, Azure Container Registry, Google Artifact Registry
• Provides authentication, access control, web UI, and APIs
• The “building” that contains many individual storage units

Container repository:

• A collection of related container images with the same name but different versions
• Identified by tags or digests (nginx:latest, nginx:1.25, nginx:alpine)
• Stored within a registry
• A “folder” or “storage unit” inside the registry building

If a registry is a library, repositories are the bookshelves, and individual container images are the books on those shelves.

For example:

• Registry: registry.example.com
• Repository: registry.example.com/my-repository
• Application (image): registry.example.com/my-repository/my-app
• Application (image) with tag: registry.example.com/my-repository/my-app:v1.2.0
• Application (image) with digest: registry.example.com/my-repository/my-app@sha256:abc123...

How Container Registries Work

Container registries expose a standardized API so that clients (Docker CLI, Kubernetes, CI/CD tools) can push and pull container images. The typical workflow looks like this.

Pushing images to a registry

1. Image build. Developer builds a container image locally with docker build or equivalent.
2. Authentication. Client authenticates with the registry (username/password, token, OAuth).
3. Layer upload. The Docker client uploads each layer. Layers already present in the registry (from other images sharing base layers) get skipped.
4. Manifest upload. The client uploads the image manifest, which is a JSON document describing the image’s layers, configuration, and metadata.
5. Tagging. The image gets tagged (v1.2.0, latest) and becomes available in the repository.

Pulling images from a registry

1. Authentication. Client authenticates if the image is in a private repository.
2. Manifest retrieval. Client downloads the image manifest to learn which layers are needed.
3. Layer download. Client downloads only the layers not already present locally.
4. Image assembly. Docker stitches layers into a usable container image.
5. Container execution. The image can now be used to run containers.

Layer deduplication and storage efficiency

Registries optimize storage by sharing layers. Container images are built in layers (typically one layer per Dockerfile instruction), and registries store each unique layer only once even when hundreds of images reference it.

For example:

• Image A uses Ubuntu base + Node.js layer + app layer
• Image B uses Ubuntu base + Python layer + different app layer
• The registry keeps the Ubuntu base layer once, and both images point to it

That deduplication cuts storage costs and speeds up image transfers, because clients only download layers they don’t already have.

Public Container Registries vs Private Container Registries

Registries split into two broad categories based on access control.

Public container registries

Public registries let anyone pull images without authentication. They work well for open-source projects, community tools, and public base images.

Popular public registries:

• Docker Hub, the default public registry with millions of container images
• GitHub Container Registry (GHCR), integrated with GitHub repositories
• Quay.io, Red Hat’s public registry for open-source projects

Use cases:

• Distributing open-source software to a global audience
• Sharing base images (Alpine Linux, Ubuntu, Python, Node.js)
• Publishing community tools and frameworks
• Educational projects and tutorials

Limitations:

• No privacy controls (your images are visible to anyone)
• Rate limiting on anonymous pulls (Docker Hub caps anonymous at 100 pulls per 6 hours)
• Limited access control and auditing
• Not a fit for proprietary software or sensitive code

Private container registries

Private registries require authentication and let organizations control exactly who accesses which images. Essential for commercial software, internal applications, and anything with security or compliance requirements.

Types:

• Cloud-hosted private registries: AWS ECR, Azure ACR, Google Artifact Registry
• Self-hosted registries: Harbor, Distribution (Docker Registry), Gitea
• Commercial registries: JFrog Artifactory, Cloudsmith, Distr

Use cases:

• Internal application development and deployment
• Commercial software distribution to customers
• Regulated industries requiring data control (healthcare, finance, government)
• Software vendors distributing to self-managed or on-premises customer environments
• Air-gapped deployments with no internet connectivity

Security features:

• Role-based access control (RBAC) defining who can push/pull specific repositories
• Image vulnerability scanning to detect security issues
• Image signing to verify authenticity and integrity
• Audit logging for compliance and tracking
• Network isolation and private networking options

For detailed comparisons of popular private and public registries, see our comprehensive container registry comparison guide.

Want to learn more?

Talk to an Expert Download White Paper

OCI Container Registry: What is OCI Compliance?

OCI (Open Container Initiative) is the industry standard that keeps container images, runtimes, and distribution methods consistent across platforms and tools. An OCI-compliant registry implements the OCI Distribution Specification, which guarantees interoperability with standard tooling.

The three OCI specifications

1. OCI Image Format Specification. Defines how container images should be structured and stored: manifest, configuration, filesystem layers.

2. OCI Distribution Specification. Standardizes the API for distributing container images: how clients push and pull images from registries. This is what makes a registry “OCI-compliant”.

3. OCI Runtime Specification. Defines how container runtimes should execute OCI-compliant containers.

Why OCI compliance matters

Portability. OCI-compliant images run across any OCI-compliant registry and runtime, avoiding vendor lock-in.

Interoperability. Docker, Kubernetes, Podman, containerd, and ORAS can all work with OCI-compliant registries.

Future-proofing. As new container technologies show up, OCI compliance keeps backward compatibility.

Beyond containers. OCI compliance isn’t just for Docker images. Modern registries use the OCI format to store Helm charts, Terraform modules, machine-learning models, WebAssembly (WASM) modules, and other software artifacts.

OCI registry conformance testing

To verify a registry is actually OCI-compliant, the OCI provides conformance testing tools. A conformant registry must support, at minimum, all APIs in the “Pull” workflow category. Full conformance includes Pull, Push, Content Discovery, and Content Management workflows.

Check conformance results to see which registries have passed official OCI testing.

Container Registry Security: Best Practices

Container registries sit inside the software supply chain, so security is non-negotiable. A compromised image can push vulnerabilities, malware, or backdoors straight into production.

Image scanning and vulnerability detection

Vulnerability scanning analyzes container images for known security issues (CVEs) in OS packages, application dependencies, and libraries. Modern registries integrate scanning tools that run automatically on push.

Good practice:

• Scan every image before it goes to production
• Configure policy to block images with critical or high-severity vulnerabilities
• Rescan stored images periodically as new vulnerabilities surface
• Use minimal base images (Alpine Linux, distroless) to cut the attack surface

For more on vulnerability scanning, see our vulnerability scanning glossary.

Image signing and verification

Image signing uses cryptographic signatures to prove an image’s authenticity and detect tampering. Tools like Docker Content Trust, Notary, and Sigstore Cosign handle signing and verification.

The flow:

1. Developer signs the image with a private key before pushing to the registry.
2. Registry stores the signature alongside the image.
3. On pull, the client verifies the signature using the public key.
4. An invalid or missing signature means the pull is rejected.

Benefits:

• Guarantees images come from trusted sources
• Detects tampering after signing
• Enables policy that only signed images can be deployed

Access control and authentication

Authentication mechanisms:

• Username/password, basic authentication for simple use cases
• Token-based auth, short-lived tokens for CI/CD pipelines
• OAuth/OIDC, integration with identity providers (Google, GitHub, Okta)
• Service accounts, machine identities for automated systems
• Mutual TLS (mTLS), certificate-based authentication for high-security environments

Authorization models:

• Role-based access control (RBAC), permissions based on user roles
• Repository-level permissions, per-repository access (read-only vs read-write)
• Tag-level restrictions, access to specific image versions only
• IP allowlists, registry access restricted to specific networks

Network security

Private networking:

• Deploy registries inside private VPCs or VLANs
• Use VPN or private endpoints instead of exposing registries to the internet
• Configure firewall rules limiting access to known IP ranges

TLS/SSL encryption:

• Always use HTTPS for registry communication
• Enforce TLS 1.2 or higher
• Use valid certificates from trusted CAs

Audit logging and monitoring

Log the events that matter:

• Image push and pull operations
• Authentication attempts, both successful and failed
• Permission changes and user management
• Image deletions or tag updates

Monitoring and alerting:

• Alert on unusual pull volumes (potential data exfiltration)
• Track which images are pulled by which systems
• Watch for deprecated or vulnerable images still in active use

Want to learn more?

Talk to an Expert Download White Paper

Container Registry for Software Distribution to Customers

Container registries are commonly used for internal development workflows, but a growing number of companies and ISVs are also using registries to distribute commercial software to external customers. That introduces a different set of requirements.

Challenges of customer-facing container registries

1. Customer-specific access control. Software vendors need to grant specific customers access to specific image versions based on license or subscription tier. Most registries are designed for internal use, where team members have broadly similar permissions. Managing hundreds of external customer accounts with varying entitlements is a different problem.

2. Usage tracking and analytics. Commercial vendors need to know which customers are pulling which images, how often, and whether they’re staying current. That data informs customer success, flags at-risk accounts, and helps with capacity planning.

3. License and entitlement management. Vendors need mechanisms to control which features or image tags customers can access based on subscription tier, prevent license violations, and enforce seat limits across distributed installations.

4. Air-gapped and disconnected environments. Many enterprise customers run air-gapped networks with no internet connectivity (military, government, critical infrastructure). Standard registries assume internet access, which makes distribution to these environments its own engineering problem.

5. Self-managed and on-premises deployments. Customers keep demanding self-managed software running in their own infrastructure (BYOC, Bring Your Own Cloud, on-premises, private clouds). Vendors need registry solutions that actually support that.

6. Customer portal experience. External customers expect self-service portals where they can view available images, generate access credentials, and manage deployments. Raw API access doesn’t cut it.

Purpose-built registries for external distribution

Registries like Docker Hub, Harbor, JFrog Artifactory, and cloud provider registries work fine for internal use. Specialized platforms like Distr are designed specifically for software vendors distributing to external customers.

Key capabilities for customer-facing distribution:

• Granular customer access control. Assign specific customers access to specific image repositories and tags.
• Usage analytics and tracking. Monitor which customers pull which images and when.
• License management integration. Enforce subscription tiers and feature access.
• Customer portals. White-labeled portals where customers view available images and create access tokens.
• Air-gapped support. Offline distribution methods for disconnected environments.

For a detailed comparison of registries that support external customer distribution, see our container registry comparison guide.

Container Registry Use Cases

CI/CD pipeline integration

Container registries are essential in modern CI/CD workflows:

1. Build stage. CI system builds a container image from source code.
2. Test stage. CI system runs automated tests against the image.
3. Scan stage. Image is scanned for vulnerabilities and policy violations.
4. Push stage. Validated image is pushed to the registry with appropriate tags.
5. Deploy stage. CD system pulls the image from the registry and deploys it.

Example with Docker:

# Build and tag image
docker build -t registry.example.com/myapp:${VERSION} .

# Run tests
docker run registry.example.com/myapp:${VERSION} npm test

# Push to registry
docker push registry.example.com/myapp:${VERSION}

# Deploy pulls from registry
kubectl set image deployment/myapp myapp=registry.example.com/myapp:${VERSION}

Microservices architecture

In microservices architectures running dozens or hundreds of services, container registries provide:

• Centralized image storage for all services
• Version management with tags for each microservice release
• Shared base images to keep consistency across services
• Dependency tracking through image layers and manifests

Multi-cloud and hybrid cloud deployments

Organizations running workloads across multiple cloud providers use registries to:

• Store images once and deploy anywhere (AWS, Azure, GCP, on-premises)
• Use registry replication to place images close to deployment regions for faster pulls
• Keep images consistent across every environment
• Support hybrid cloud architectures mixing cloud and on-premises infrastructure

Edge computing and IoT

For edge deployments running on distributed devices:

• Bandwidth efficiency: layer caching minimizes data transfer to edge locations
• Offline operation: local registry caches allow updates without constant internet connectivity
• Version control: manage software versions across thousands of edge devices
• Selective updates: deploy different image versions to different device tiers

Air-gapped and high-security environments

Air-gapped environments need specific registry considerations:

• Offline registry deployment: self-hosted registry inside the air-gapped network
• Manual image transfer: physical media (USB drives, external drives) moving images across the air gap
• Registry mirroring: syncing images from external registries into the air-gapped registry
• Signature verification: making sure images haven’t been tampered with on the way across

Container Registry Best Practices

Tagging strategy

Semantic versioning for releases:

myapp:1.2.3
myapp:1.2
myapp:1
myapp:latest

Git commit tags for traceability:

myapp:sha-7f8d92a
myapp:pr-456
myapp:dev-7f8d92a

Environment-specific tags:

myapp:production
myapp:staging
myapp:development

Avoid overwriting tags: many registries support immutable tags to prevent accidental overwrites. Enable that, and myapp:1.2.3 will always resolve to the same image.

Image lifecycle management

Retention policies that automatically delete:

• Untagged images (CI/CD leftovers)
• Images older than N days with no recent pulls
• Images superseded by newer versions

Cleanup automation:

• Schedule regular cleanup jobs to prune old images
• Configure registries to expire images by age or usage
• Keep recent versions and production images indefinitely

Monitoring image sprawl:

• Track registry storage growth over time
• Identify repositories with the most images
• Find abandoned or unused images

Secure image distribution

Pull images by digest, not just by tag:

# Tags can change; the digest guarantees the exact version
docker pull myapp@sha256:abc123def456...

Use private registries for proprietary software:

• Don’t push internal or customer applications to public registries
• Even “private” Docker Hub repositories deserve a second look for sensitive workloads, because a dedicated private registry usually offers more controls

Enable vulnerability scanning:

• Configure automated scanning on push
• Set policy to block deployment of images with critical vulnerabilities
• Rescan stored images regularly as new CVEs get published

Implement image signing:

• Sign production images before pushing to registry
• Configure Kubernetes admission controllers to allow only signed images
• Verify signatures before deploying

Registry performance optimization

Use registry caching and mirroring:

• Set up local registry mirrors for frequently pulled base images
• Configure pull-through caches to reduce bandwidth and speed up pulls
• Replicate registries to multiple regions for geo-distributed teams

Optimize image size:

• Use minimal base images (Alpine, distroless)
• Combine RUN commands to reduce layers
• Use multi-stage builds to exclude build tools from the final image
• Remove unnecessary files before creating image layers

Leverage layer caching:

• Order Dockerfile instructions from least frequently changed to most frequently changed
• Put dependency installation before application code
• That ordering maximizes layer reuse across builds

Want to learn more?

Talk to an Expert Download White Paper

Artifact Registry vs Container Registry: Beyond Docker Images

Modern registries increasingly support OCI artifacts beyond container images. An artifact registry stores any OCI-compliant artifact type:

Helm charts, Kubernetes application packages:

helm push my-chart.tgz oci://registry.example.com/helm-charts

Terraform modules, infrastructure-as-code templates:

oras push registry.example.com/terraform/aws-vpc:v1.0 ./module:application/vnd.hashicorp.terraform.module.v1+tar.gz

Machine learning models, AI/ML model files packaged as OCI artifacts:

oras push registry.example.com/models/bert-base:v1.0 model.pkl:application/vnd.myorg.model

WebAssembly (WASM) modules, lightweight, portable binary modules:

oras push registry.example.com/wasm/serverless-fn:v1.0 function.wasm:application/vnd.wasm.content.layer.v1+wasm

Software Bill of Materials (SBOM), security metadata about software components:

# SBOM attached to container image
oras attach registry.example.com/myapp:v1.0 sbom.json:application/vnd.cyclonedx+json

Generic OCI artifacts, any file type wrapped in OCI format using ORAS.

The line between “container registry” and “artifact registry” has blurred as registries adopted OCI standards. Most modern registries support both container images and other OCI artifacts, which is why “artifact registry” is the more accurate label.

Docker Registry Mirror and Pull-Through Cache

A registry mirror (also called pull-through cache) is a registry that caches images from upstream registries like Docker Hub. When a client requests an image, the mirror checks its cache first. If the image is there, the mirror serves it immediately. If not, the mirror pulls it from the upstream registry, caches it, and returns it to the client.

Benefits:

• Faster pulls, local cache vs internet latency
• Reduced bandwidth, upstream bandwidth is used once per image
• Rate limit avoidance, no Docker Hub rate limits
• Reliability, cached images stay available even when the upstream registry is down

Setting up a Docker Hub mirror:

Configure a mirror in /etc/docker/daemon.json:

{"registry-mirrors": ["https://mirror.example.com:5000"]}

Restart Docker daemon:

sudo systemctl restart docker

Want to learn more?

Talk to an Expert Download White Paper

Distribute Software with Distr’s Container Registry

Distr provides an OCI-compliant artifact registry built specifically for software vendors and ISVs distributing containerized applications to customers. Where most registries are designed for internal use, Distr focuses on the external case:

• Customer access management: grant specific customers access to specific image versions based on their license
• Usage tracking and analytics: see which customers are pulling which images and when
• Customer portal: white-labeled portal where customers view available images and create access credentials
• Air-gap support: distribute to disconnected environments without internet connectivity
• Open source: available as managed SaaS or self-hosted

For detailed comparisons with other registries, see our container registry comparison guide.

← Back to Glossary

Frequently Asked Questions

What is the difference between a container registry and a Docker registry?

A Docker registry is a specific type of container registry built for Docker images. "Container registry" is the broader term, which also covers OCI-compliant registries that may store Helm charts, Terraform modules, and other artifacts alongside container images.

What is the difference between a registry and a repository?

A registry is the service or platform that hosts repositories. A repository is a collection of related container images with the same name but different versions. Docker Hub is a registry. nginx is a repository within Docker Hub. nginx:latest is a specific image tag within that repository.

What is the most popular container registry?

Docker Hub is the most widely used public container registry, with millions of images. For private, enterprise use, AWS ECR, Azure ACR, and Google Artifact Registry are popular cloud-hosted options, and Harbor is the leading open-source self-hosted registry.

How do I push an image to a Docker registry?

Tag the image with the registry URL, authenticate with docker login, then run docker push. The image becomes available in the registry under the tag you specified.

Can I use a container registry for Helm charts?

Yes. Modern OCI-compliant registries support Helm charts. Helm v3.8.0+ has native OCI registry support, so you can push and pull Helm charts from container registries just like Docker images.

What is the difference between Docker Hub and private registries?

Docker Hub is a public registry where anyone can pull images (with rate limits). Private registries require authentication, let organizations control access, enforce security policies, and keep proprietary images confidential. Private registries can be cloud-hosted (AWS ECR, Azure ACR) or self-hosted (Harbor, Distribution).

How much does a container registry cost?

It varies. Docker Hub offers limited free public repositories. Cloud provider registries (ECR, ACR, GAR) bill for storage (roughly $0.10/GB/month) and bandwidth. Self-hosted registries have server/infrastructure costs but no per-GB fees. Enterprise registries like JFrog Artifactory have license fees. Distr offers free open-source and paid managed options.

Can I run a registry on-premises or in an air-gapped environment?

Yes. Self-hosted registries like Harbor, Distribution, and Distr self-hosted can run entirely on-premises or in air-gapped environments with no internet connectivity. Common practice in regulated industries and high-security deployments.

What is OCI compliance and why does it matter?

OCI (Open Container Initiative) compliance means a registry follows standardized specifications for image format and distribution. That makes your images portable across OCI-compliant tools and registries, so you are not locked to a single ecosystem.

How do I choose between cloud-hosted and self-hosted registries?

Cloud-hosted registries (AWS ECR, Azure ACR, Distr) have minimal operational overhead, automatic updates, and pay-per-use pricing. Self-hosted registries (Harbor, Distribution) give you full control, work in air-gapped environments, and avoid cloud egress fees, at the cost of operational management.

What is the best registry for software vendors distributing to customers?

Software vendors distributing commercial applications to external customers should use purpose-built registries like Distr, which provide customer-specific access controls, usage analytics, license management, and support for self-managed and air-gapped customer deployments.

Want to learn more?

Talk to an Expert Download White Paper