Docker Push and Pull: Moving Container Images

WHY IT EXISTS: Docker packages applications into portable images. But how do you get those images from your development machine to a production server, or share them with a teammate? The push and pull commands solve this distribution problem by providing a standard way to transfer images to and from a central repository called a registry.

THE MENTAL MODEL: Think of a Docker registry like a Git remote repository (e.g., GitHub), but for compiled artifacts (Docker images) instead of source code. docker pull is like git pull; it fetches an image from the registry to your local machine. docker push is like git push; it uploads your locally built image to the registry for others to use or for deployment.

HOW IT WORKS: Docker images are composed of layers. When you pull an image, Docker is smart enough to only download the layers you don't already have locally, making subsequent pulls of similar images much faster. push is also optimized to only upload layers the remote registry doesn't already possess. Before you can push, you must tag your image with the registry's address, like gcr.io/my-project/my-app:v1. This tag tells the Docker daemon which registry to send the image to. If you don't specify a registry hostname, it defaults to the public Docker Hub.

WHEN TO USE IT: Use docker pull to get base images for your Dockerfiles (e.g., python:3.9-slim) or to run pre-built applications (e.g., docker run hello-world, which implicitly pulls the image if it's not local). Use docker push to share your application images with your team, store them for automated deployments, or contribute to public repositories. Pushing images is a core part of any CI/CD pipeline that uses containers.

WHEN NOT TO USE IT: For transferring an image to a single, air-gapped machine without a registry, using docker save (to create a .tar file) and docker load (to import it) can be simpler. For development on a single machine, you don't need to push and pull; you just build and run the image locally. Never push images containing secrets or proprietary code to a public registry.

ONE CANONICAL EXAMPLE: To run the official Nginx web server, you first get the image from Docker Hub with docker pull nginx:latest. Docker contacts the registry, downloads the necessary layers, and assembles the image locally. To share your own app, you would first tag it for a specific registry, like docker tag my-local-app my-registry.com/my-org/my-app:1.0. Then you would upload it with docker push my-registry.com/my-org/my-app:1.0.