10.1.1.2 Registry Image Pull

A registry image pull downloads an image from a registry to the local machine, the operation that retrieves a previously published image so it can actually be run, completing the distribution cycle that began with that image being pushed somewhere else.

The Basic Pull Process

Specifying an image's full name and tag retrieves it from the appropriate registry.

docker pull postgres:16

Without an explicit registry prefix, Docker Hub is assumed by default.

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

An explicit registry prefix directs the pull to that specific, named registry instead.

Why Authentication May Be Required for Certain Pulls

While Docker Hub's public images can typically be pulled without authentication, a private registry (or a private repository on a public registry) requires prior login before a pull succeeds.

docker login registry.example.com
docker pull registry.example.com/myteam/private-image:1.0

Why Already-Present Layers Aren't Re-Downloaded

If layers from the requested image already exist locally — from a previous pull of a related image sharing those layers — only the missing layers actually need to be downloaded.

docker pull node:20-alpine
docker pull node:20.5-alpine

If both versions share most of their underlying layers, the second pull completes considerably faster than downloading the entire image from scratch would.

Pulling Implicitly as Part of Running a Container

A pull happens automatically, if needed, as part of starting a container from an image not already present locally.

docker run -d postgres:16

Why Registry Image Pull Matters

Pulling is the operation that actually makes a previously published image usable on a given machine, completing the full distribution cycle and making container images genuinely portable across whatever machines or environments need to run them.