Docker Push and Pull Commands Reference

Docker Push Command

The docker push command uploads your locally built or modified images to a registry, making them available for others to use.

docker push [OPTIONS] NAME[:TAG]

docker push myregistry.example.com/myapp:1.0

Push Process

When you run the docker push command, Docker performs the following steps:

1. Authenticates with the registry (if required)
2. Compresses and prepares layers for upload
3. Checks which layers already exist in the registry
4. Uploads only the layers that don't already exist in the registry
5. Uploads the image manifest, which references the layers

The push operation is optimized to only upload layers that don't already exist in the registry, making subsequent pushes of similar images much faster.

Docker Pull Command

The docker pull command downloads images from a registry to your local machine, allowing you to run containers based on those images.

docker pull [OPTIONS] NAME[:TAG|@DIGEST]

docker pull nginx:latest

Pull Process

When you run the docker pull command, Docker performs the following steps:

1. Authenticates with the registry (if required)
2. Downloads the image manifest
3. Checks which layers already exist locally
4. Downloads only the layers that don't already exist locally
5. Decompresses and verifies the layers
6. Stores the layers in the local Docker storage

Like pushing, the pull operation is optimized to only download layers that don't already exist locally, making subsequent pulls of similar images much faster.

Docker Registry Concepts

Registry Types

Docker supports several types of registries:

• Docker Hub: Docker's public registry (default)
• Private registries: Self-hosted or vendor-provided private registries
• AWS ECR, Google GCR, Azure ACR: Cloud provider registries
• GitHub Container Registry: GitHub's container registry

Image Naming

Docker image names typically follow this format:

[registry/][namespace/]repository[:tag]

For example:

• nginx:latest - An image from Docker Hub in the official namespace
• username/myapp:1.0 - An image from Docker Hub in a user's namespace
• registry.example.com/team/project:v1.0.0 - An image from a private registry
• gcr.io/project-id/image:tag - An image from Google Container Registry

Authentication

Most registries require authentication before you can push images or pull private images. You can authenticate using the docker login command:

docker login [OPTIONS] [SERVER]

For Docker Hub:

docker login

For a private registry:

docker login registry.example.com

Examples

# Tag a local image for Docker Hub
docker tag myapp:latest username/myapp:latest

# Push the image to Docker Hub
docker push username/myapp:latest

# Pull the image from Docker Hub
docker pull username/myapp:latest

# Log in to the private registry
docker login registry.example.com

# Tag an image for the private registry
docker tag myapp:latest registry.example.com/myteam/myapp:1.0.0

# Push the image to the private registry
docker push registry.example.com/myteam/myapp:1.0.0

# Pull the image from the private registry
docker pull registry.example.com/myteam/myapp:1.0.0

# Inspect an image to get its digest
docker inspect --format='{{index .RepoDigests 0}}' nginx:latest

# Pull an image using its digest
docker pull nginx@sha256:2ab30d6ac53580a6db8b657abf0f68d75360ff5cc1670a85acb9402a3c7c293e

# Pull all tags for the nginx repository
docker pull --all-tags nginx

# List all pulled tags
docker images nginx

# Tag an image with multiple tags
docker tag myapp:latest username/myapp:latest
docker tag myapp:latest username/myapp:1.0.0
docker tag myapp:latest username/myapp:stable

# Push all tags to Docker Hub
docker push --all-tags username/myapp

# Pull the arm64 version of the image
docker pull --platform linux/arm64 nginx:latest

# Pull the amd64 version of the image
docker pull --platform linux/amd64 nginx:latest

# AWS ECR
aws ecr get-login-password | docker login --username AWS --password-stdin 012345678910.dkr.ecr.us-east-1.amazonaws.com
docker push 012345678910.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

# Google GCR
gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin gcr.io
docker push gcr.io/myproject/myapp:latest

# Azure ACR
az acr login --name myregistry
docker push myregistry.azurecr.io/myapp:latest

Common Issues and Troubleshooting

Notes and Limitations

• Docker Hub has pull rate limits for anonymous and free accounts. Consider authenticating or using a paid account for production environments.
• Image layers are uploaded and downloaded individually, so large images with many layers might take longer to push or pull.
• The --all-tags option can consume significant bandwidth and storage if a repository has many tags.
• Docker Content Trust is not enabled by default and requires additional setup.
• When pulling by digest, you must use the exact digest format. Tags can be updated to point to different images, but digests are immutable.
• Images built for a specific platform (e.g., linux/amd64) may not run on other platforms without emulation or multi-platform support.
• Docker credentials are stored in ~/.docker/config.json by default. Secure this file appropriately.
• Some registries may have retention policies that automatically delete older tags or unused images.
• Network bandwidth can significantly impact push and pull performance, especially for large images.