You’ve built a container image on your laptop. It works perfectly. Now you need that exact same image to run on a production server halfway across the world — and maybe on a teammate’s machine, and on three more servers next month. How does the image get from where it was built to everywhere it needs to run? You don’t email it around. You push it to a container registry, and everyone pulls it from there.
A registry is one of those pieces of infrastructure that’s easy to overlook until you realize almost every container workflow quietly depends on it. Once you understand what a registry does, the whole “build once, run anywhere” promise of containers finally connects end to end. So let’s walk through it from the ground up.
What a container registry actually is
A container registry is a server whose job is to store and distribute container images. Think of it as a warehouse for images: you upload an image into it, and later anyone with permission can download that same image, byte for byte, onto any machine.
If you’ve used a code hosting service for source code, the mental model is nearly identical. A registry is to container images what a code host is to source files. You push an image up to share it, and you pull an image down to use it. The registry holds the canonical copy that everyone agrees on.
Here’s why this matters: a container image is the frozen, ready-to-run package of your app — your code plus the exact operating system files, libraries, and settings it needs. Building that image is one thing. Getting it to run somewhere else is a separate problem, and the registry is the answer to it. Without a registry, every machine would have to rebuild the image itself, and you’d lose the guarantee that they’re all running the exact same thing.
Registry vs. repository vs. image — three nested words
These get mixed up constantly, so pin them down now. A registry is the whole service (the warehouse). Inside it, a repository is a named collection holding all the versions of one particular image — for example, a repository called web-app. Inside that repository, each individual version is an image identified by a tag, like web-app:1.4 or web-app:latest. So the full address reads as registry / repository : tag. One registry holds many repositories; one repository holds many tagged images.
Push and pull: the two operations that matter
Almost everything you do with a registry boils down to two verbs.
Push uploads an image from your machine to the registry. You do this after you build an image, when you want to make it available to other machines. The registry stores it and gives it an address others can reach.
Pull downloads an image from the registry onto a machine that needs to run it. A production server pulls the image, then starts a container from it. A teammate pulls the same image to run it locally and gets an identical environment.
Here’s the typical flow, from build to running in production:
YOUR MACHINE REGISTRY PRODUCTION SERVER
│ │ │
│ 1. build the image │ │
│ ─────────┐ │ │
│ ◄────────┘ │ │
│ │ │
│ 2. push image ─────────►│ │
│ │ (stores the image) │
│ │ │
│ │◄──── 3. pull image ────────│
│ │ │
│ │ 4. run container ──────│ ─────┐
│ │ │ ◄────┘The beauty of this is the separation of concerns. The machine that builds the image and the machine that runs it never need to talk to each other directly. The registry sits in the middle as a neutral handoff point. That’s exactly what makes automated deployment pipelines possible: a build server pushes a fresh image, and one or many run servers pull it — no coordination required beyond “they both know the registry address.”
Tags: how you point at a specific version
Every image in a repository is identified by a tag. A tag is just a human-readable label attached to a particular image version — 1.4, 2.0.1, stable, latest. When you pull, you say which tag you want, and the registry hands you exactly that image.
# pull a specific, pinned version
pull registry.example.com/web-app:1.4
# pull whatever is currently tagged "latest"
pull registry.example.com/web-app:latestTags are how you control which version runs where. Your production servers might pull web-app:1.4 so they stay on a known, tested release, while a staging server pulls web-app:latest to test the newest build. Change the tag your servers pull, redeploy, and you’ve rolled forward — or back.
`latest` is not a magic 'newest' guarantee
The tag latest is a common source of confusion. It is not a special, auto-updating pointer to the truly newest image — it’s just an ordinary tag that happens to be named “latest.” It points to whatever image was most recently pushed with that tag. Two problems follow. First, latest can change under your feet, so two servers pulling latest an hour apart might get different images — bad for reproducibility. Second, if you never push a latest tag, it simply won’t exist. For anything you actually deploy, pin a specific version tag like 1.4 so you always know precisely what’s running.
For the same reason, serious teams often pull images by their digest — a content-based fingerprint (a long hash) of the exact image bytes. A tag can be moved to point at a different image later; a digest can’t, because it is the image’s content. Pulling by digest guarantees you get byte-for-byte the same image every single time, which is the gold standard for reproducible deployments.
Public vs. private registries
Registries come in two broad flavors, and the difference is simply who can pull from them.
A public registry lets anyone download images without logging in. This is where official base images live — the minimal, ready-made images for operating systems and language runtimes that you build your own images on top of. When you start an image “from” a Linux base or a language runtime, that base is usually pulled, openly, from a public registry. Public registries are how the container ecosystem shares common building blocks.
A private registry requires authentication — you log in before you can push or pull. This is where you keep your own application images, the ones containing your proprietary code and configuration. You absolutely do not want those to be world-readable. Private registries can be a service you pay for, or one you run yourself on your own infrastructure.
PUBLIC REGISTRY PRIVATE REGISTRY
┌──────────────────┐ ┌──────────────────┐
│ base OS images │ │ your-app:1.4 │ 🔒
│ language images │ │ your-api:2.0 │ 🔒
│ open tools │ │ internal-job:9 │ 🔒
└──────────────────┘ └──────────────────┘
anyone can pull login requiredA very common setup mixes both: you pull your base images from a public registry, build your application on top, then push the finished application image to a private registry that only your team and your servers can reach. Public for the shared ingredients, private for your finished product.
How a registry stores images efficiently
You might assume each image is stored as one giant file, but registries are cleverer than that, and it’s worth knowing why — it explains why pushes and pulls are often surprisingly fast.
A container image is built in layers, stacked on top of each other. The bottom layer might be the base operating system, the next layer the language runtime, the next your installed dependencies, and the top layer your own code. Each layer is stored separately in the registry, identified by a hash of its contents.
Because layers are shared and content-addressed, the registry only ever stores one copy of each unique layer. If ten of your images all build on the same OS base layer, that layer is stored once, not ten times. And when you pull an image, you only download the layers you don’t already have locally. Change one line of your code, rebuild, and push — only the tiny top layer that changed actually travels over the network. The huge base layers, already in the registry and already on the target machine, are skipped.
IMAGE = a stack of layers (each stored once, by hash)
┌────────────────────────┐ ← your code (changes often, tiny)
├────────────────────────┤ ← dependencies (changes sometimes)
├────────────────────────┤ ← language runtime (changes rarely)
└────────────────────────┘ ← base OS (changes almost never)
push/pull only moves the layers that are new — the rest is reusedThis layer sharing is one of the quiet reasons containers feel so lightweight in practice. The first pull of a fresh base might be sizeable, but every pull after that mostly reuses what’s already there.
Where registries fit in a deployment pipeline
In a real workflow, the registry is the hinge between building and running. Picture an automated pipeline:
- A developer pushes new code to the project.
- A build server compiles it and builds a fresh container image, tagged with the new version.
- The build server pushes that image to the registry.
- The deployment step tells the production servers to pull the new image and restart their containers from it.
Notice that the registry is what lets steps 2 and 4 happen on completely different machines, possibly minutes or hours apart, with full confidence they’re dealing with the identical image. It’s the shared source of truth. This is also why registry access control matters for security: anyone who can push to your registry can effectively change what your production servers run, so push permissions are guarded carefully, and servers are usually given pull-only access.
The registry is your single source of truth for 'what's running'
When something breaks in production, one of the most useful questions is “exactly which image is running?” Because every deployed container comes from a tagged (or, better, digest-pinned) image in your registry, you can trace any running container straight back to a specific, immutable artifact in the registry — and from there to the exact code that built it. That traceability, from a live container all the way back to the bytes in the registry, is a huge part of why registries are non-negotiable infrastructure for teams running containers seriously.
Why registries matter
Containers promise “build once, run anywhere,” but that promise is empty without a way to move the built thing from where it was made to everywhere it needs to go. The registry is that way. It’s the distribution layer that turns a local image into something the whole world — or just your fleet of servers — can run identically.
It also gives you three things that matter enormously in practice: a single canonical copy everyone agrees on, versioning through tags and digests so you always know what’s deployed, and access control so your private code stays private while shared base images stay open. Strip those away and you’re back to copying files around by hand and hoping every machine ended up with the same thing — which is exactly the chaos containers were invented to escape.
If you’ve been following along, this slots neatly next to what you already know: an image is the package, and the registry is where that package lives and travels. Together they’re the full answer to how a container you built in one place ends up running, unchanged, everywhere else.
Wrapping up
Here’s the whole picture in one place:
- A container registry is a server that stores and distributes container images — a warehouse you push images into and pull them out of.
- The two core operations are push (upload an image to share it) and pull (download an image to run it). The registry sits between the machine that builds and the machine that runs.
- Images are organized as registry / repository : tag. A tag points at a version; pulling by digest guarantees the exact same bytes every time.
latestis just an ordinary tag, not a guaranteed-newest pointer — pin a real version for anything you deploy.- Public registries (anyone can pull) hold shared base images; private registries (login required) hold your own application images.
- Registries store images in shared, content-addressed layers, so unchanged layers are stored and transferred only once — which keeps push and pull fast.
- In a deployment pipeline, the registry is the single source of truth between building and running, and its access control is a real security boundary.
Next, it’s worth looking at what keeps containers safely separated from each other and from the host they share — the idea of container isolation, and why running many containers on one machine doesn’t turn into one big tangled mess.
