The simplest way to remove a Docker image

To delete a Docker image, you use the docker rmi command followed by the image name or ID. Open your terminal or command prompt and type docker rmi image-name, where image-name is the name of the image you want to remove. Docker will delete that image from your system.

Before you can delete an image, any containers running from that image must be stopped and removed first. If you try to delete an image while a container based on it is still running, Docker will refuse and show you an error message. This safety feature prevents you from accidentally breaking a container that depends on that image.

The image name usually appears as repository:tag — for example, ubuntu:20.04 or nginx:latest. If you do not specify a tag, Docker assumes you mean the latest tag. You can also delete an image by its ID, a long string of letters and numbers that uniquely identifies it.

Key Takeaways

  • Use docker rmi image-name to delete an image, where image-name is the repository and tag (like ubuntu:20.04).
  • Stop and remove any running containers from that image before you delete it, or Docker will refuse the deletion.
  • Use docker images to list all images on your system and find the exact name or ID of the one you want to remove.
  • Add the -f flag (docker rmi -f image-name) only if a container is still using the image and you want to force deletion anyway.

Finding the image name or ID before you delete

Run docker images to see a list of every image stored on your computer. The output shows columns for REPOSITORY, TAG, IMAGE ID, CREATED, and SIZE. Find the image you want to delete and note either its name (the REPOSITORY and TAG columns together) or its IMAGE ID.

Image IDs are long strings like sha256:abc123def456, but Docker usually accepts just the first 12 characters. Using the name is simpler if you remember it — for example, docker rmi postgres:13 is easier to read than docker rmi 5a4526e952f0.

Stopping and removing containers before deletion

If Docker refuses to delete an image and says a container is using it, you must stop 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.

Stop the container with docker stop container-id or docker stop container-name. Then remove it completely with docker rm container-id. Only after the container is gone can you delete the image it was based on.

This two-step process (stop, then remove) exists because a stopped container still takes up disk space and still claims ownership of its image. Removing the container fully releases that claim, allowing you to delete the image without breaking anything.

Forcing deletion when a container is still attached

If you want to delete an image without stopping and removing its containers first, add the -f flag: docker rmi -f image-name. The -f stands for force, and it tells Docker to delete the image even though a container is using it.

Forcing deletion is risky. The container will still exist, but it will no longer have access to the image layers it depends on. The container may fail to restart or behave unpredictably. Use force deletion only if you are certain you no longer need that container and are willing to accept the consequences.

Removing multiple images at once

To delete several images in one command, list them all after docker rmi: docker rmi image1 image2 image3. Docker will remove each one in order, stopping only if it encounters an error with one of them.

You can also delete all images that match a pattern. For example, docker rmi $(docker images -q --filter "dangling=true") removes all dangling images — images that have no tag and are not used by any container. Dangling images usually accumulate over time as you rebuild images with the same name.

Checking disk space after deletion

Deleting an image frees up the disk space it occupied. Run docker system df to see how much space Docker is using overall, broken down by images, containers, and build cache. This command shows you the total size of all images, how much space unused images are taking up, and how much you could free by cleaning up.

If you want to remove all unused images at once — not just one — run docker image prune. This removes every image that is not currently in use by a container. Add the -a flag (docker image prune -a) to also remove images that are tagged but not running, which frees up more space.

Frequently Asked Questions

What happens to containers when I delete an image?

Containers based on that image will stop working if they are still running. Stopped containers will remain on your system but will fail if you try to restart them. Always remove containers before deleting their image, unless you are certain you no longer need them.

Can I recover an image after I delete it?

No. Deletion is permanent. If you need the image again, you must rebuild it or pull it from a registry like Docker Hub. If the image came from Docker Hub, you can always pull it again with docker pull image-name.

Why does Docker refuse to delete an image?

Docker refuses deletion when a container (running or stopped) is still using that image. Stop and remove the container first with docker stop and docker rm, then try deleting the image again. If you see a different error, check that you typed the image name correctly.

What is the difference between docker rmi and docker image rm?

They do the same thing. docker rmi is the older, shorter command. docker image rm is the newer form that groups image-related commands together. Both work identically, so use whichever you prefer.

Should I delete images I am not using right now?

Yes, if you know you will not need them again soon. Unused images take up disk space. If you might need an image later, you can always pull it again from Docker Hub or rebuild it. Deleting unused images is a normal part of keeping your system clean.