docker-pull
Download a Docker image from a registry
TLDR
Download a specific Docker image
Download a specific Docker image in quiet mode
Download all tags of a specific Docker image
Download a Docker images for a specific platform, e.g. linux/amd64
Display help
SYNOPSIS
docker pull [OPTIONS] NAME[:TAG|@DIGEST]
PARAMETERS
--all-tags, -a
Downloads all tagged images for the repository. Instead of just one tag (e.g., 'latest'), it fetches every version available.
--disable-content-trust
Skips image content trust verification. By default, Docker attempts to verify the integrity and publisher of an image using Notary. This flag bypasses that check.
--platform string
Sets the target platform if the image is multi-platform capable (e.g., linux/amd64, linux/arm64). This is crucial for pulling images designed for different CPU architectures.
--quiet, -q
Suppresses verbose output during the pull process, showing only error messages or essential information.
DESCRIPTION
The docker pull command is used to download Docker images from a configured registry, most commonly Docker Hub by default, or a private registry.
Docker images are read-only templates or blueprints that contain all the necessary components (application code, libraries, system tools, dependencies) to create a Docker container. When you execute docker pull, the command fetches all the required image layers for the specified image and tag (or digest) from the remote registry. These layers are then stored locally in Docker's image cache on your machine.
If no tag is specified for an image name, Docker automatically attempts to pull the latest tag. Once an image is pulled, it becomes available locally for use by other Docker commands, such as docker run, which creates and starts a container from the image. This command is fundamental for deploying pre-built applications or environments within the Docker ecosystem.
CAVEATS
- Network Requirement: docker pull requires an active internet connection to reach remote registries.
- Disk Space: Pulled images consume local disk space, which can accumulate rapidly, especially with large or numerous images.
- Content Trust: While content trust is a security feature, it can sometimes cause issues if the image is not signed or if Notary services are unavailable. Using --disable-content-trust bypasses this security check.
- Registry Access: If pulling from a private registry, you must first authenticate using docker login.
- Bandwidth Consumption: Large images can consume significant network bandwidth, impacting download times and data usage.
IMAGE LAYERS AND EFFICIENCY
Docker images are built up from a series of read-only layers. When you pull an image, Docker checks which layers you already have locally. It only downloads the new or updated layers, making the pull process highly efficient, especially for images that share common base layers (e.g., multiple Ubuntu-based images).
DOCKER REGISTRIES
A Docker registry is a storage and distribution system for Docker images. Docker Hub is the default public registry, hosting millions of public and private images. Organizations can also set up private registries (e.g., Docker Trusted Registry, Harbor) to store their proprietary images securely. docker pull communicates directly with these registries to retrieve images.
HISTORY
The docker pull command has been a cornerstone of the Docker CLI since its early days, shortly after Docker's initial public release around 2013. As Docker revolutionized containerization, the ability to easily fetch pre-built application images from a centralized repository (Docker Hub) became a fundamental workflow. Its development has focused on efficiency, leveraging Docker's layered filesystem to download only missing image layers, and security, with the introduction of content trust mechanisms. The command has evolved alongside Docker itself, adapting to new features like multi-platform images and improved registry interactions, maintaining its central role in the container lifecycle.
SEE ALSO
docker run(1), docker build(1), docker images(1), docker push(1), docker login(1), docker search(1)