Delete a Docker image with a single command

To delete a Docker image from your system, use docker rmi followed by the image name or ID. For example, docker rmi ubuntu:20.04 removes the Ubuntu 20.04 image. If you have the image ID instead of the name, docker rmi a1b2c3d4e5f6 works the same way. Docker will confirm the deletion by showing the image ID and the layers it removed.

The command only works if no running or stopped containers are using that image. If a container depends on it, Docker will refuse to delete the image and tell you which container is in the way. You have two choices: delete the container first, or use the -f flag to force removal (though this is riskier and not recommended for beginners).

Key Takeaways

  • Use docker rmi image-name or docker rmi image-id to delete a single image.
  • Docker will block deletion if any container — running or stopped — still uses that image.
  • Delete the dependent container first with docker rm container-name, then delete the image.
  • Use docker images to list all images on your system and find the exact name or ID you need.
  • Clean up multiple unused images at once with docker image prune to free disk space.

Find the exact image name or ID before deleting

Before you run the delete command, you need to know what you are deleting. Run docker images to see every image stored on your system. The output shows the repository name (like ubuntu or nginx), the tag (like 20.04 or latest), the image ID (a long hex string), and the size.

The full image name is the repository plus the tag, separated by a colon. So ubuntu:20.04 is the repository ubuntu with tag 20.04. If you do not specify a tag, Docker assumes latest. You can delete by either the full name (docker rmi ubuntu:20.04) or by the image ID alone (docker rmi a1b2c3d4e5f6). The ID is unique even if multiple tags point to the same image.

Stop and remove containers before deleting their image

If Docker refuses to delete an image and says a container is using it, you must remove that container first. Run docker ps -a to list all containers, including stopped ones. Find the container that uses the image you want to delete — the output shows which image each container was built from.

Delete the container with docker rm container-name or docker rm container-id. If the container is still running, stop it first with docker stop container-name, then remove it. Once the container is gone, the image is no longer in use and you can delete it with docker rmi image-name.

Removing a container does not delete the image it came from — the image stays on disk until you explicitly delete it. This is why you can have many containers from the same image, and why you need to clean up both separately.

Use docker image prune to delete all unused images at once

If you want to free up disk space without deleting images one at a time, use docker image prune. This command removes every image that no container — running or stopped — depends on. It will ask you to confirm before deleting anything.

Add the -a flag with docker image prune -a to also remove images that are tagged but not currently in use. Without the -a flag, Docker keeps images that have custom tags, even if no container uses them. The -a version is more aggressive and frees more space, but make sure you do not need those images before running it.

Docker will show you how much disk space was freed when the command finishes. This is useful after you have deleted many containers and want to clean up the images they left behind.

Understand what happens when you delete an image

When you delete an image, Docker removes the image layers from disk and frees up the space they occupied. The image ID, name, and all its tags disappear from docker images output. If you later need that image again, you will have to pull it from a registry like Docker Hub, which downloads it fresh.

Deleting an image does not affect any containers that were already created from it — those containers have their own copy of the filesystem and will keep running. It only prevents you from creating new containers from that image. If you delete an image and then try to start a new container from it, Docker will fail with an error saying the image does not exist.

Recover from accidental deletion

If you delete an image by mistake, you cannot undo it directly. However, if the image came from a public registry like Docker Hub, you can pull it again with docker pull image-name. This downloads the image fresh and takes a few seconds to a few minutes depending on the image size and your internet speed.

If the image was custom-built on your machine and you did not push it to a registry, recovery is not possible through Docker. Your best option is to rebuild it from the Dockerfile if you still have the file. If you do not have the Dockerfile either, the image is permanently lost.

Frequently Asked Questions

What does the -f flag do when deleting an image?

The -f flag forces deletion even if a container is using the image. This can leave containers in a broken state because they depend on the image layers. Avoid using -f unless you are certain no container needs the image. Always delete the container first instead.

Can I delete multiple images with one command?

Yes. List multiple image names or IDs after docker rmi, separated by spaces: docker rmi ubuntu:20.04 nginx:latest postgres:13. Docker will delete all three. If any one fails because a container uses it, the others will still be deleted.

Does deleting an image delete my data inside containers?

No. Containers have their own filesystem separate from the image. Deleting the image does not touch any data in running or stopped containers. The container keeps working until you stop and remove it.

Why does docker rmi say the image is in use when I have no containers?

You likely have a stopped container that still uses the image. Run docker ps -a to see all containers including stopped ones. Remove the stopped container with docker rm container-name, then try deleting the image again.

How much disk space will I free by deleting an image?

Run docker images and look at the SIZE column for the image you want to delete. That is roughly how much space you will recover, though the actual amount may be slightly less if the image shares layers with other images on your system.