Remove Docker images | all, force, none tag, cache, Docker Hub

This post covers seven key points about deleting Docker images. Focusing on the docker image rm command, we'll cover almost all types of docker image deletion methods, including deleting specific images, forcing deletion, full deletion, deleting unused images, deleting dag, deleting build cache, and even deleting docker hub images.

1. Docker Specific Image Delete Commands

Commands to remove one or more images from Docker have the following basic format.

docker image rm [OPTIONS] IMAGE [IMAGE...]

It acts like the docker rmi command in the old command scheme, with the name of the image, its name and tags, and the image ID in the IMAGE position. Available options include --force, which performs a forced delete, and --no-prune, which does not remove the parent image.

To delete a specific image from Docker, it must not be used by any currently running containers. Therefore, you can delete an image by issuing the following command against such an image.

If you wanted to remove the latest version of the nginx image, you would issue the following command.

$ docker image rm nginx:latest
Untagged: nginx:latest
Untagged: nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
Deleted: sha256:f9c14fe76d502861ba0939bc3189e642c02e257f06f4c0214b1f8ca329326cda
Deleted: sha256:419f8948c50c723f2a5ac74428af3d804b5d0079d6df8f7f827663cf10cbc366
Deleted: sha256:1030aac4f1a8096ed58d3d4a2df55dd1b1b27d919ad156d97ad1f68081d0051a
Deleted: sha256:7d90b49d96c3036539ef144ecc27c01de03902d8ea166a0f7b77d11d3779c4bd
Deleted: sha256:551acb210764654af31b6cd51adaa74edc9a202587c3395fe0e9f95a2e097f8b
Deleted: sha256:3c530958db4c75c6fb409f339367aaf9a1e163c84718c035d4b09bebc83f43e7
Deleted: sha256:8cbe4b54fa88d8fc0198ea0cc3a5432aea41573e6a0ee26eca8c79f9fbfa40e3

You can delete by image name, as shown above, or by image ID, as shown below.

$ docker image ls ubuntu:latest
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
ubuntu       latest    3b418d7b466a   5 weeks ago   77.8MB
 
$ docker image rm 3b418d
Untagged: ubuntu:latest
Untagged: ubuntu@sha256:dfd64a3b4296d8c9b62aa3309984f8620b98d87e47492599ee20739e8eb54fbf
Deleted: sha256:3b418d7b466ac6275a6bfcb0c86fbe4422ff6ea0af444a294f82d3bf5173ce74
Deleted: sha256:b8a36d10656ac19ddb96ef3107f76820663717708fc37ce929925c36d1b1d157

2. Forced image deletion

As briefly mentioned in Section 1, there are three main cases where deleting a Docker image is not possible. In these cases, you'll need to use the --force option to force deletion. Let's take a look at the three common cases where deletion is not possible.

2.1. When deleting a Docker image fails

The image is being used by a running container: By default, Docker does not allow you to delete an image that is being used by a running/stopping container. To delete such an image, you must first stop or delete that container.
The image is the parent of another image: Docker images are a collection of layers, and one image can be the base for another image. In this case, if you try to delete the underlying image, the operation will be rejected. To resolve this issue, you must first delete all dependent images.
Docker is running out of disk space: Docker might temporarily use additional disk space during the process of deleting an image. If you run out of disk space, deleting an image might fail.

In this situation, you should try to delete the image again after fixing the problem. For example, stop or delete the running container, delete any child images that use the parent image, or free up disk space if necessary.

In some cases, however, you may end up wasting a lot of time and money trying to resolve the situation. If you're using it for development, or to respond to the unexpected, you may want to proceed with a forced delete.

2.2. How to force delete images

Forcing the deletion of an image is easy. Just add the --force option to the rm command. Here is the image used by the stalled container. Let's see the result of a force delete.

$ docker image rm php:7
Error response from daemon: conflict: unable to remove repository reference "php:7" (must force) - container 086591af79a4 is using its referenced image 0b50b7a54cab
 
$.docker image rm --force php:7
Untagged: php:7
Untagged: php@sha256:a4325b962bf0ced295f9f6ea275837f504109fcb8497cb0fd340094bc5b5f29f
Deleted: sha256:0b50b7a54cab40ebbb65919b3502dbff938bbdaa6c4e18339d73745fc73ccdf5

I got an error when I tried a normal delete, but the forced delete completed successfully.

3. Delete unused images completely (none)

When downloading multiple Docker images or building your own kernel images, you will naturally accumulate images with image names of <none>. These are intermediate images created to optimize image build speed or output size. These are most likely unused images.

Docker provides a command to remove all these dangling images at once. This is called docker image prune.

Currently, you will see many <none> images in the list, as shown below.

Images in dangling state After typing the prune command and answering yes to the prompt, the removal will proceed as shown below.

docker image prune result If there are any images that were not deleted in this process, it is most likely for one of the three reasons we saw in Section 2.1.

4. Delete all images completely

This is not recommended, but if you want to completely delete all images in your local environment, regardless of their state, you can use the following method.

$ docker image rm --force  $(docker image ls --all --quiet)

The docker image ls --all --quiet command simply prints a list of all image IDs in the local environment, and the $() syntax in the shell script is used to pass the list of IDs as an argument to the preceding command. The rm command has a --force option which allows you to delete images in any state.

Be sure to back up your images before using these commands to avoid accidentally deleting important images.

5. Delete Image Tags

The command to remove an image tag is docker image rm. If you feel that something is wrong, you're right. It's the same as the command to delete a specific image, and Docker does not provide a separate tag delete command.

In Docker, you can only delete an image tag if the image has multiple tags. If the image has no other tags, the entire image is deleted. However, if the image has multiple other tags, only the tag specified by the command will be deleted, and the image will still exist.

To see this in action, let's add a new tag to an Nginx image. To add a new tag to an image, use the docker image tag command.

$ docker image tag nginx:latest nginx:my-tag
 
$ docker image ls nginx
REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
nginx        latest    f9c14fe76d50   6 days ago      143MB
nginx        my-tag    f9c14fe76d50   6 days ago      143MB

We've added a new tag named my-tag to the nginx:latest image, and when we run the ls command we see two tags with the same image ID.

Let's delete the my-tag tag.

$ docker image rm nginx:my-tag
Untagged: nginx:my-tag
 
$ docker image ls nginx
REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
nginx        latest    f9c14fe76d50   6 days ago      143MB
nginx        1.21      f8f4ffc8092c   20 months ago   133MB

Since the Nginx image in question had multiple tags, you can see that only the tags are deleted and the image still exists.

Similarly, to change image tags, you can either delete the image and rebuild the same image with new tags. Alternatively, you can add a new tag and delete the existing tag from the image.

Deleting a tag on a Docker image makes it impossible to find images associated with that tag, so it's important to check if the image has any other tags before deleting it.

6. Clear your image build cache

When Docker builds an image, it saves the results of intermediate steps as a cache to reuse the next time it builds. This cache takes up disk space, so you should clear it when necessary.

To clear Docker's build cache, use the docker builder prune'command:

This command will delete all unused build caches. If you want to delete all existing build caches, you can run it with the --all option.

Deleting caches can increase disk space in your local environment, but it can also increase image build time. It's a good process to think about these tradeoffs as you run the command.

7. Delete a Docker Hub image

Here's the process for deleting an image from Docker Hub.

log into Docker Hub.
click Repositories.
Click the repository containing the image you want to delete.
Navigate to the Tags tab.
Click the Delete button to the right of the tag you want to delete.
In the pop-up window, click Delete to delete the tag, or click Delete All Tags to delete all tags in the repository.

Note: When you delete an image from Docker Hub, it is permanently removed from Docker Hub. It cannot be restored, so we recommend backing it up if necessary before deleting it.

8. Final Thoughts

In this post, we've covered seven key points about deleting Docker images. In particular, we've covered almost every type of image deletion method, including deleting specific images, force deleting, full deleting, deleting unused images, deleting dags, deleting build cache, and even deleting Docker Hub images. We hope this helps you with your Docker image deletion process.

inspect