10.1.1.1 Registry Image Push

A registry image push uploads a locally built (or locally tagged) image to a registry, making it available there for others, or other systems, to subsequently pull, the step that actually publishes an image beyond the local machine it was built on.

The Basic Push Process

An image must first be tagged with the full registry-qualified name it should be pushed under, then pushed using that name.

docker build -t myapi:2.3.0 .
docker tag myapi:2.3.0 registry.example.com/myteam/myapi:2.3.0
docker push registry.example.com/myteam/myapi:2.3.0

The intermediate tagging step gives the locally built image the fully qualified name the target registry expects, distinct from its initial, simpler local tag.

Why Authentication Is Typically Required

Pushing to most registries — particularly private ones, but even certain namespaces on public registries — requires prior authentication, ensuring only authorized users can publish images under a given namespace.

docker login registry.example.com
docker push registry.example.com/myteam/myapi:2.3.0

Why Only New or Changed Layers Are Actually Uploaded

Because images are composed of layers, a push only needs to upload layers the registry doesn't already have — if most of an image's layers already exist there from a previous push, only the differing layers need to be transferred.

docker push registry.example.com/myteam/myapi:2.4.0

If 2.3.0 was pushed previously and shares most layers with 2.4.0, this push completes considerably faster than a full image's worth of data would suggest.

Verifying a Push Succeeded

Confirming the pushed image is actually available in the registry validates the push completed successfully.

docker pull registry.example.com/myteam/myapi:2.3.0

Why Registry Image Push Matters

Pushing is the essential step that transforms a locally built image into something genuinely shareable, making it available to any other authorized system or person that needs to pull and run that exact same image.