Download Docker images | directory, path, to file, to local, limit, error, policy, secret

In this post, we'll cover six of the most frequently asked questions about downloading Docker images. We'll start with the docker image local download command, where to find the local download path, how to download files, download limits, error resolution, and a little bit about Kubernetes.

1. The docker image local download command

Docker images can be built directly, but they can also be downloaded from several different Docker container registries. The most popular registry is Docker Hub, but others include Google's GCR, Amazon's ECR, and MS's ACR. The commands to download Docker images locally from these registries are as follows

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

where NAME is the name of the image, and TAG or DIGEST is a separator that selects a particular image from among several versions of the same image. If no tag or digest value is specified, the image corresponding to the :latest tag will be downloaded.

The tags you assign to an image can change from time to time, so it's possible to download an image with the same tag over time, but it's not the same image. In this case, you can use a digest value to ensure that you are downloading the exact same image. You can find these values in the RepoDigests section of the inspect command output, as shown below.

For more information about the docker image inspect command, see the Image inspection post

$ docker image inspect --format '{ {.RepoDigests} }' nginx:latest
[nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305]
Copy

Either value, tag, or digest will download an image that looks like this

$ docker image pull nginx@sha256:af296b...092305
docker.io/library/nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305: Pulling from library/nginx
Digest: sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
Status: Image is up to date for nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
docker.io/library/nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
 
$ docker image pull nginx:latest
latest: Pulling from library/nginx
Digest: sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
Status: Image is up to date for nginx:latest
docker.io/library/nginx:latest

2. Image Local Download Path Location

When you download a Docker image using the pull command in Section 1, the image data is placed in a path that Docker manages for you.

Typical local image download path locations are as follows

Linux: /var/lib/docker/
MacOS: ~/Library/Containers/com.docker.docker/Data/vms/0/
Windows: C:\ProgramData\Docker\

However, it's generally not appropriate to access this docker directly. This is because Docker manages images and containers with separate data structures and algorithms. If you want to save and load images as files, see the next Section 3.

3. Commands for downloading image files

There are times when you may need to save a particular image as a file in order to transfer or distribute it over a network, or for backup and restore purposes. To save a locally downloaded image as a file, use the following command format.

docker image save -o IMAGE_NAME IMAGE

In the IMAGE_NAME part, specify the path where the file should be saved and the filename with the .tar extension. If you only specify a filename, it will automatically be saved under that filename in the current directory.

$ mkdir docker-images
 
$ docker image save -o  ~/docker-images/nginx-image nginx:latest
 
$ ls docker-images
nginx-image

Once saved to a file, the image can be reloaded with the load command. Please specify the path and name of the image file after the -i option.

$ docker image load -i docker-images/nginx-image.tar
Loaded image: nginx:latest

4. Docker Hub download limits

To provide better service, Docker Hub imposes different limits on the number of downloads per day depending on the user plan. The maximum number of downloads per day is as follows

Unsigned users: 100 downloads/6 hours
Free plan users: 200 downloads/6 hours
Paid plan users: 5000 downloads/day

If you make more than the maximum number of download requests, you will receive the following log message

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

5. How to fix the no basic auth credentials error

This error message occurs when your Docker CLI cannot find the credentials it needs to authenticate to the Docker registry, including Docker Hub. Typically, this can happen if you need to log in but are not logged in, or if your credentials are incorrect.

In these cases, you can try to log in with the docker login command, or log out with the docker logout command, and then try to log in again. If the login is successful, the credentials are stored in the ~/.docker/config.json file.

If the login attempt fails, you can also try backing up the config.json file to a different directory and retrying.

6. Docker with Kubernetes: Image Pull Policy, Docker Pull Secret

Container orchestration tools like Kubernetes set the Docker pull policy and secret.

6.1. Image Pull Policy

Image pull policy refers to a rule that determines when Kubernetes should download an image when running a container with a Docker image. In Kubernetes, there are three policies.

Always: This policy causes Kubernetes to always download images from the registry. Even if an image with the same tag already exists locally, it will be ignored and a new image will be fetched from the registry. This is the default policy when the image tag is :latest.
IfNotPresent: This policy causes Kubernetes to fetch an image from the registry only if the image does not exist locally. If an image with the same tag already exists locally, it will use that image. This is the default policy when the image tag is not :latest.
Never: This policy tells Kubernetes not to download images from the registry. Kubernetes will always try to use a locally available image, and will return an error if one does not exist.

These policies can be set in the Kubernetes pod specification.

6.2. Docker Pull Secret

A Docker pull secret is used by container orchestration tools, such as Kubernetes, to store access credentials for a specific Docker registry. You can use this secret to download a Docker image.

Secrets are typically in JSON file format, and the Kubernetes CLI provides the following command to create a secret

$ kubectl create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL

The above command creates a secret file named my-secret, which can be referenced in the Kubernetes Pod specification through the imagePullSecrets entry.

7. Conclusion

In this article, we've covered the top 6 most frequently asked questions about downloading Docker images. We've covered everything from the command to download Docker images locally, where to find the local download path, how to download files, download limits, troubleshooting, and a little bit about Kubernetes. We hope this helps you through the process of downloading and storing images.

remove inspect