Unable to Find the Image Locally in Docker

If you use a Docker image for the first time, you will encounter the “unable to find the image locally” message. This is not an error message but a notification that tells you that Docker will try pulling the specified image from the registry since the image is unavailable in your local machine.

An example is as follows:

$ Docker run -it --rm alpine sh

As you can see from the output, we can see the “unable to find the image alpine:latest locally”.

Causes of the “Unable to Find the Image Locally” Message

Image Not Pulled

This message’s first and most common cause is if the image is not pulled. To use an image to create a container, the target image must be pulled from the Docker hub. Although Docker is configured to automatically pull the image from the hub if it is unable to find it locally, you can manually download it using the “pull” command:

For example:

$ docker pull alpine:latest

This should pull the latest version of the Docker Alpine image.

Incorrect Name or Tag

The second cause of the “unable to find the image locally” error occurs if the specified name, image, and tag are incorrect. Including a typo in the name/tag of an image can lead to this error.

An example is as follows:

$ docker run -itd ubuntuu

As you can see from the previous command, there is a typo in the image name. Running the previous command returns an error as follows:

Unable to find image ‘ubuntuu:latest’ locally

docker: Error response from daemon: pull access denied for ubuntuu, repository does not exist or may require ‘docker login’: denied: requested access to the resource is denied.

See 'docker run --help'.

Unbuilt Image

This error may occur in other cases if the target image is not built locally using the Docker “build” command. This is especially common if you are using a custom image.

To resolve this error, you can navigate to the directory that contains the Dockerfile and execute the “build” command to create the image:

$ docker build -t image_name:tag .

This should build and output the image with the specified command. You can then reference the name in your Docker “run” command.

Docker Daemon Not Running

You may also encounter this error if the Docker daemon is not running. You can use the “systemctl” command to check if the service is running as follows:

sudo systemctl status docker

Output:

docker.service - Docker Application Container Engine
Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
Active: inactive (dead) since Fri 2023-09-08 05:00:42 UTC; 13s ago
TriggeredBy: ● docker.socket
Docs: https://docs.docker.com
Process: 868 ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock (code=exited, status=0/SUCCESS)
Main PID: 868 (code=exited, status=0/SUCCESS)
CPU: 1.179s

In this case, we can see that the Docker daemon is stopped. To fix this error, we can use the command as follows:

$ sudo systemctl start docker

Once started, you can re-run the command to pull the image and build the container.

Caching Issues

Lastly, you can encounter the “unable to find the image locally” message if Docker is having image caching issues. You can clean up the cache and re-run the command to fix this.

$ sudo docker system prune -a

Conclusion

In this short tutorial, we explored the potential causes of the “unable to find the image locally” in Docker when attempting to pull an image or building a container.