Push to Docker Hub and Pull on Another Machine

You built an image on one computer and want to run it on another. The image has to travel through a registry: you push it from the first computer, and you pull it on the second. Docker Hub is the usual registry. This page shows the steps in the order you type them. I ran them against a registry in a container on my own computer. I did not run the Docker Hub commands, because I did not use a real account.

What you need

• The image, tagged with a version (see the tagging tutorial).
• A registry address and, for Docker Hub, an account and an access token.
• On the second computer: Docker and network access to the registry.

On the first computer: tag and push

The image name must start with the registry's address. For Docker Hub the address is implied, and the name starts with your Hub user name. For the registry in this demo, it starts with localhost:5055. Start it first.

docker run -d --name hubtest-registry -p 127.0.0.1:5055:5000 registry:2 | Out-Null
Start-Sleep -Seconds 3

FROM alpine:3.24
CMD ["echo", "hello from another machine"]

Set-Location hubtest-demo
docker build -q -t hubtest-app:1.0.0 . | Out-Null
docker tag hubtest-app:1.0.0 localhost:5055/hubtest-app:1.0.0
docker push localhost:5055/hubtest-app:1.0.0 2>&1 | Select-String "push refers|digest:" | ForEach-Object { $_.ToString().Trim() }

The push refers to repository [localhost:5055/hubtest-app]
1.0.0: digest: sha256:10ca90c3dee5efd779b4432fd8570ff5ef8dc45d10707b4102b0cc46a0f767d4 size: 855

The Docker Hub version of the same steps, not run here, with your own user name:

docker login --username YOUR-HUB-NAME
docker tag hubtest-app:1.0.0 YOUR-HUB-NAME/hubtest-app:1.0.0
docker push YOUR-HUB-NAME/hubtest-app:1.0.0

docker login asks for a password. Give it an access token that you create in your Hub account settings, with the smallest permission that works. Never write the token in a file in your project.

Check what the registry has

Before you walk to the other computer, ask the registry itself. This reads the manifest without pulling any layers.

docker buildx imagetools inspect localhost:5055/hubtest-app:1.0.0 2>&1 | Select-String "^(Name|MediaType|Digest):" | ForEach-Object { $_.ToString().Trim() }

Name:      localhost:5055/hubtest-app:1.0.0
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:10ca90c3dee5efd779b4432fd8570ff5ef8dc45d10707b4102b0cc46a0f767d4

If this command finds the image, the push worked, and any machine that can reach the registry can pull it.

On the second computer: pull and run

The second computer needs no build tools and no source code. It needs the full name.

docker image rm localhost:5055/hubtest-app:1.0.0 hubtest-app:1.0.0 | Out-Null
docker run --rm localhost:5055/hubtest-app:1.0.0

Unable to find image 'localhost:5055/hubtest-app:1.0.0' locally
1.0.0: Pulling from hubtest-app
7edc23427a41: Download complete
Digest: sha256:10ca90c3dee5efd779b4432fd8570ff5ef8dc45d10707b4102b0cc46a0f767d4
Status: Downloaded newer image for localhost:5055/hubtest-app:1.0.0
hello from another machine

I removed my local copies first, so the image had to come from the registry. docker run pulls an image that is missing, so a separate docker pull is optional. I used one computer, so my "second machine" was an empty image store. The steps on a real second computer are the same, with the registry's real address.

For Docker Hub the second computer runs docker run YOUR-HUB-NAME/hubtest-app:1.0.0. If the repository is private, run docker login there first.

Clean up

docker rm -f hubtest-registry
docker image rm hubtest-app:1.0.0

Related course: Docker Intermediate.