Tag, push and pull images with Docker Hub and other registries

An image built on your machine only exists there. To run it on a server, in Compose on another host or in Kubernetes, you push it to a registry and pull it from there. The registry is encoded in the image name, so the steps are the same whichever registry you use.

How image names work

A full image reference looks like registry/namespace/repository:tag. Parts you leave out get defaults:

• nginx:1.27 means docker.io/library/nginx:1.27: Docker Hub, the official library namespace.
• myuser/myapp:1.0 means docker.io/myuser/myapp:1.0: a user or organisation on Docker Hub.
• ghcr.io/myorg/myapp:1.0 is GitHub Container Registry; registry.example.com:5000/team/myapp:1.0 is a private registry with a port.
• A missing tag means latest. For deployments use a version or the Git commit hash so you always know what is running.

Log in

docker login
docker login ghcr.io
docker login registry.example.com

Without a hostname docker login targets Docker Hub. Use an access token rather than your account password: Docker Hub tokens are created under Account settings, and for GitHub use a personal access token with the write:packages scope. In scripts pass the token on standard input instead of the command line, so it does not land in shell history:

echo "$REGISTRY_TOKEN" | docker login ghcr.io -u myuser --password-stdin

Tag and push

docker build -t myapp:1.0 .
docker tag myapp:1.0 myuser/myapp:1.0
docker tag myapp:1.0 myuser/myapp:latest
docker push myuser/myapp:1.0
docker push myuser/myapp:latest

docker tag does not copy anything; it adds a second name to the same image ID. push uploads only the layers the registry does not already have, so pushing a rebuilt image is usually quick. You can also build with the final name directly: docker build -t ghcr.io/myorg/myapp:1.0 ..

Pull and run elsewhere

docker pull myuser/myapp:1.0
docker run -d --name app -p 8000:8000 myuser/myapp:1.0

docker run pulls automatically if the image is missing locally, but it does not check for a newer image with the same tag. Run docker pull (or docker compose pull) first when you want the latest build of a moving tag.

Build for another CPU architecture

An image built on an Apple Silicon Mac is arm64 and will not run on a typical amd64 server unless you build for that platform. Buildx can build and push a multi-platform image in one step:

docker buildx build --platform linux/amd64,linux/arm64 -t myuser/myapp:1.0 --push .

Run a local registry for testing

The registry is itself an image. This gives you a private registry on localhost:5000 with its data in a volume:

docker run -d --name registry -p 5000:5000 -v registry-data:/var/lib/registry --restart unless-stopped registry:2
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0
curl http://localhost:5000/v2/_catalog

Docker treats localhost as an insecure registry that may use plain HTTP. Any other hostname needs TLS, or must be listed under insecure-registries in /etc/docker/daemon.json, which is acceptable only on a lab network.

Clean up local copies

docker rmi myuser/myapp:1.0 myuser/myapp:latest
docker image prune

Removing a tag locally does not touch the registry. Careful: docker image prune -a removes every local image that no container is using, and pulling them again costs time and bandwidth.

Official documentation

• docker image push reference
• Docker Hub repositories
• Multi-platform builds