The basic command to remove a Docker image

To delete a Docker image, use docker rmi followed by the image name or ID. For example, docker rmi ubuntu:20.04 removes the Ubuntu 20.04 image. You can also use the image ID instead of the name — Docker will accept either one.

Before you delete an image, make sure no container is currently using it. If a container is running or stopped but still exists, Docker will refuse to remove the image and show an error. You must stop and remove the container first, then remove the image.

If you want to force removal even when a container is using it, add the -f flag: docker rmi -f ubuntu:20.04. This is rarely necessary and can leave your system in an inconsistent state, so use it only when you understand the consequences.

Key Takeaways

  • The command docker rmi image_name removes an image, but only if no container is using it.
  • You must stop and remove any containers based on that image before you can delete the image itself.
  • Use docker images to list all images on your system and find the ones you want to remove.
  • Deleting unused images frees up disk space, which matters if you work with many large images.

Finding which images you have and their size

Run docker images to see every image stored on your system. The output shows the repository name, tag, image ID, when it was created, and the size on disk. Large images like database servers or machine learning frameworks can consume several gigabytes each.

To see the actual disk space each image uses, including layers shared between images, run docker system df. This command shows images, containers, and build cache separately, so you can see where your storage is going. If you have pulled many versions of the same image — for example, python:3.9, python:3.10, and python:3.11 — they may share some layers, so the total disk use is less than the sum of their individual sizes.

You can also filter the image list to show only images you have not used recently. Run docker images --filter "dangling=true" to see images with no tag and no running container — these are almost always safe to delete.

Removing containers before removing images

A container is a running or stopped instance of an image. Even if a container is stopped, Docker still considers the image "in use" and will not let you delete it. You must remove the container first.

List all containers — running and stopped — with docker ps -a. Find the container ID or name of the one you want to remove. Then run docker rm container_id to delete it. If the container is still running, stop it first with docker stop container_id, then remove it.

If you want to remove all stopped containers at once, run docker container prune. Docker will ask for confirmation before deleting them. This frees up space and makes it easier to delete the images those containers were based on.

Deleting multiple images at once

To remove more than one image in a single command, list them all: docker rmi ubuntu:20.04 alpine:latest nginx:1.21. Docker will remove each one in order, stopping only if it encounters an error.

You can also remove all images with a specific name but different tags. For example, docker rmi python:3.9 python:3.10 python:3.11 removes all three versions of Python. If you want to keep one version and remove the others, list only the ones you want gone.

To remove all images at once — a drastic step that you should only take if you are starting fresh — run docker rmi $(docker images -q). This command lists all image IDs and passes them to docker rmi. Docker will refuse if any image has a running or stopped container, so you must clean up containers first.

Cleaning up unused images and build cache

Docker accumulates unused layers and build cache over time, especially if you build images frequently. Run docker image prune to remove all images with no tag and no container using them. Docker will show you how much space this frees and ask for confirmation.

To also remove build cache from failed or old builds, run docker builder prune. This does not touch images or containers — only the intermediate layers Docker keeps to speed up future builds. If you build images often, this can reclaim significant space.

For a complete cleanup, run docker system prune. This removes stopped containers, unused images, and build cache all at once. Add the -a flag — docker system prune -a — to also remove images that are not currently in use by any container, even if they have a tag. Be careful with this option; it removes more than you might expect.

What happens when you delete an image

When you delete an image, Docker removes the layers that make up that image from disk. If another image shares some of those layers, Docker keeps the shared layers intact. This is why two images based on the same operating system do not take up twice the space — they reuse the common foundation.

Once an image is deleted, you cannot run a new container from it unless you pull it again from a registry like Docker Hub. If the image was built locally and not pushed to a registry, deletion is permanent. If you built an image yourself and might need it again, consider tagging it and pushing it to a registry before you delete the local copy.

Frequently Asked Questions

Can I delete an image if a container is using it?

Not without forcing it. Docker will show an error if you try. You must stop and remove the container first with docker stop and docker rm, then delete the image. You can force deletion with docker rmi -f, but this can leave your system inconsistent.

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

They do the same thing. docker rmi is the older, shorter syntax. docker image rm is the newer syntax that groups image commands together. Both work identically.

If I delete an image, can I get it back?

If the image was pulled from Docker Hub or another registry, you can pull it again. If you built it locally and did not push it anywhere, it is gone permanently. Always push custom images to a registry if you might need them later.

How do I know which images are safe to delete?

Images with no tag and no container using them are almost always safe to delete. Run docker images --filter "dangling=true" to find them. For tagged images, check when they were last used and whether you still need that version.

Does deleting an image affect running containers?

No. A running container has its own copy of the image layers in memory. Deleting the image does not stop the container or change its behavior. You can only delete an image if no container — running or stopped — is based on it.