Delete a Docker image with a single command

To delete a Docker image from your computer, use docker rmi followed by the image name or ID. For example, to remove an image called nginx, type docker rmi nginx and press Enter. Docker will remove that image from your system, freeing up the disk space it was using.

If you have multiple versions of the same image (called tags), you can delete a specific version by adding a colon and the tag name: docker rmi nginx:1.19 removes only version 1.19, while docker rmi nginx:latest removes the most recent version. Without specifying a tag, Docker removes the image labeled latest by default.

You can also delete multiple images at once by listing them: docker rmi nginx postgres redis removes all three in a single command. Docker will tell you which images were deleted and how much space was freed.

Key Takeaways

  • Use docker rmi imagename to delete an image by name, or docker rmi imageid to delete by the unique identifier Docker assigns.
  • Docker will refuse to delete an image if a container is currently using it, even if that container is stopped — you must delete the container first.
  • Use docker images to see all images on your system, including their names, tags, IDs, and sizes, so you know what you are deleting.
  • The -f flag forces deletion of an image even if a container depends on it, but this can leave containers broken and unable to start.
  • Dangling images (layers with no name or tag) accumulate over time and waste space; docker image prune removes them all at once.

Find the image name or ID before you delete

Before you can delete an image, you need to know its name or ID. Run docker images to list every image stored on your computer. The output shows the repository name (like nginx or postgres), the tag (like latest or 1.19), the image ID (a long string of letters and numbers), the creation date, and the size in megabytes or gigabytes.

The image ID is unique to that specific image. If you see the same repository name listed multiple times with different tags, each one is a separate image taking up space. For example, you might have nginx:1.19, nginx:1.20, and nginx:latest all stored separately. You can delete them one at a time or all together.

If you are not sure what an image is for, look at the repository name — it usually describes the software it contains. Common examples are nginx (a web server), postgres (a database), redis (a cache), and python (a programming language). If you built a custom image yourself, you gave it a name when you created it.

Delete containers before you can delete their images

Docker will not let you delete an image if a container is using it, even if that container is stopped and not running. You must delete the container first. Run docker ps -a to see all containers on your system, including stopped ones. Look for any container that shows the image name you want to delete in the Image column.

To delete a container, use docker rm containername or docker rm containerid. For example, docker rm my-nginx-server removes the container called my-nginx-server. Once the container is gone, you can delete the image it was using.

If you try to delete an image and Docker says it is in use, this is why. The error message will tell you which container is holding it. Delete that container, then delete the image.

Use the force flag only when you understand the consequences

The -f flag forces Docker to delete an image even if a container depends on it: docker rmi -f nginx. This bypasses the safety check that normally prevents you from deleting an image that is in use. However, forcing deletion leaves the container in a broken state — it will still exist on your system, but it will not be able to start because its image is gone.

Use the force flag only if you are certain you want to delete both the image and any containers using it, and you are willing to clean up the broken containers afterward. In most cases, it is safer to delete the container first with docker rm, then delete the image normally.

If you force-delete an image and a container breaks, you can still remove the broken container with docker rm. The container will not restart, but it will stop taking up space once you delete it.

Clean up dangling images to reclaim disk space

Over time, Docker accumulates dangling images — layers that have no name or tag and are not used by any container. These happen when you rebuild an image or pull a new version of an image you already have. The old version becomes dangling and wastes space, but docker images does not always show them clearly.

To see only dangling images, run docker images -f dangling=true. To delete all of them at once, use docker image prune. Docker will ask you to confirm, then remove every dangling image and tell you how much space was freed. This is safe — dangling images are not used by any container.

You can also delete all unused images (images that are not used by any container, whether dangling or not) with docker image prune -a. This is more aggressive and will remove images you might want to keep, so use it only if you are sure.

Delete images by ID when names are not unique

If you have built custom images or pulled from multiple sources, you might have images with the same name but different IDs. In this case, delete by ID instead of by name. The image ID is the long string shown in the IMAGE ID column when you run docker images. You can use the full ID or just the first 12 characters.

For example, if two images are both named myapp but have different IDs, run docker rmi abc123def456 to delete only the one with that ID. Using the ID is more precise than using the name, which would delete the first matching image it finds.

You can also combine deletion by ID with other flags: docker rmi -f abc123def456 forces deletion of the image with that ID, even if a container is using it.

Understand what happens to disk space after deletion

When you delete a Docker image, the space it was using becomes available again on your hard drive. However, the space is not always returned to the operating system when ready — it depends on how Docker stores images on your system. On most Linux systems, the space is freed right away. On Windows and Mac, Docker runs in a virtual machine, and the space may not be returned to your main operating system until you restart Docker or the virtual machine.

If you delete a large image and do not see the disk space freed, try restarting Docker. On Windows, right-click the Docker icon in the system tray and select Restart. On Mac, click the Docker icon in the menu bar and select Restart. On Linux, run systemctl restart docker (you may need to use sudo).

To see how much space Docker is using on your system, run docker system df. This shows the total size of all images, containers, and volumes, and how much space could be freed by removing unused items.

Frequently Asked Questions

What happens if I delete an image I need later?

You can pull the image again from Docker Hub or another registry. If it is a public image like nginx or postgres, run docker pull nginx to read it again. If it is a custom image you built yourself, you will need to rebuild it using the Dockerfile or other source code you have saved.

Can I delete an image that is currently running in a container?

No. Docker will refuse to delete an image if a container using that image is running or even stopped. You must stop the container with docker stop containername, then delete it with docker rm containername, then delete the image. The force flag (-f) can override this, but it will break the container.

How do I delete all images at once?

Run docker rmi $(docker images -q) to delete every image on your system. This is aggressive and will remove images you might need later. A safer approach is docker image prune -a, which removes only unused images and asks for confirmation first.

What is the difference between deleting an image and deleting a container?

An image is the blueprint — the stored software and files. A container is a running instance of that image. Deleting an image removes the blueprint from your disk. Deleting a container removes a running instance. You can have one image and many containers using it, so you usually delete containers before deleting the image.

Why does Docker say an image is in use when no container is running?

A stopped container still counts as "in use." Run docker ps -a to see all containers, including stopped ones. Delete the stopped container with docker rm containername, then try deleting the image again.