Remove a Docker Image

The short answer

To remove and un-tag a single Docker image from your local machine, you can use the [.inline-code]docker rmi[.inline-code] command followed the the identifier of the image you want to remove:

$ docker rmi <image_id>

Note that you will first need to stop and remove all the containers currently using this image in order to be able to remove it.

You can learn more about this by reading our article on how to remove all stopped Docker containers.

[#easily-recall-syntax-using-ai]Easily retrieve this command using Warp’s AI Command Search[#easily-recall-syntax-using-ai]

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Search feature:

Entering [.inline-code]docker remove image[.inline-code] in the AI Command Search will prompt an [.inline-code]docker[.inline-code] command that can then quickly be inserted into your shell by doing [.inline-code]CMD+ENTER[.inline-code].

[#removing-from-local-machine]Removing an image from the local machine[#removing-from-local-machine]

A Docker image can be removed using either its short or long identifier, its tag, or its digest. To get this information, you can run the [.inline-code]docker images[.inline-code] command, which will list all the locally downloaded images:

$ docker images

You can then use one of the methods described below to remove one or more images. Alternatively, you can also read our article on how to remove all Docker images at once.

[#removing-using-a-tag]Removing an image using its tag[#removing-using-a-tag]

A tag is a string of characters used to identify a specific version of an image (e.g. [.inline-code]latest[.inline-code], [.inline-code]v1.0[.inline-code]).

To remove an image based on its tag, you can use the following syntax:

$ docker rmi <image:tag>

For example, the following command will remove the [.inline-code]mysql[.inline-code] image version 8:

$ docker rmi mysql:8

Note that if an image has one or more tags referencing it, you must remove all of them before the image is removed.

[#removing-using-a-digest]Removing an image using its digest[#removing-using-a-digest]

A Docker image digest is an immutable identifier created during the build time of the image.

Since a digest cannot be altered or tampered with, unlike a name or tag, it is sometimes preferable to use it in order to prevent the accidental removal of unwanted images, especially when working with scripts or automation.

To remove a Docker image using its digest, you can use the following syntax:

$ docker rmi <image>@<digest>

For example, the following command will remove the [.inline-code]mysql[.inline-code] image based on its digest value:

$ docker rmi mysql@sha256:15f069202c46cf861ce429423ae3f8dfa6423306fbf399eaef36094ce30dd75c

Note that to list all images including their digest, you can use the [.inline-code]docker images --digests[.inline-code] command.

[#forcing-the-removal]Forcing the image removal[#forcing-the-removal]

To force the removal of a Docker image, regardless of whether it is currently used by containers or has multiple tags associated with it, you can use the [.inline-code]docker rmi[.inline-code] command with the [.inline-code]-f[.inline-code] flag (short for force) as follows:

$ docker rmi -f <image>

Note that this command should be used with caution as it may provoke the unexpected disruption of running applications.

[#removing-from-a-docker-registry]Removing an image from a Docker registry[#removing-from-a-docker-registry]

To remove an image from an online Docker registry, you must first authentication to the registry using the [.inline-code]docker login[.inline-code] command:

$ docker login <registry_url>

List all the images present in the registry using the [.inline-code]docker search[.inline-code] command:

$ docker search <registry_url>

And finally, run the [.inline-code]docker rmi[.inline-code] command using the following syntax:

$ docker rmi <registry_url>/<image>:<tag>

For example:

$ docker rmi docker.io/library/nginx:latest

[#removing-from-artifactory]Removing an image from Artifactory[#removing-from-artifactory]

To remove a Docker image from Artifactory, you can use the following [.inline-code]curl[.inline-code] command:

$ curl -u <username>:<password> -X DELETE "<artifactory_url>/artifactory/<repository>/<image>:<tag>"

Where:

• [.inline-code]username[.inline-code] is your Artifactory username.
• [.inline-code]password[.inline-code] is your Artifactory password.
• [.inline-code]artifactory_url[.inline-code] is the URL of your Artifactory instance.
• [.inline-code]repository[.inline-code] is the name of the repository where the Docker image is stored.
• [.inline-code]image[.inline-code] is the name of the Docker image you want to remove.
• [.inline-code]tag[.inline-code] is the tag of the Docker image you want to remove.