🚨 Docker Error Guide: 'image is being used by running container' — Cannot Delete Image

Overview

Docker refuses to delete an image because a container is still using it:

Error response from daemon: conflict: unable to delete 5d0da3dc9764 (cannot be forced) - image is being used by running container 3f9ac1b2e7d4

An image cannot be removed while any container — running or stopped — is based on it, because the container’s writable layer sits on top of the image’s read-only layers. The (cannot be forced) phrase is the important part: when the container is running, even docker rmi -f will not remove the image. You must deal with the dependent container first.

Symptoms

• docker rmi <image> fails with conflict ... image is being used by running container <id>.
• docker rmi -f still refuses when the container is running (cannot be forced).
• docker image prune -a skips the image and leaves it in place.
• After a redeploy, an old image will not delete because an orphaned container still references it.
• The image shows a non-zero dependent count when you inspect what is using it.

Common Root Causes

• A running container is based on the image. The most direct cause; the daemon protects layers in active use.
• A stopped container still references it. Even Exited containers pin their image (though these allow rmi -f).
• Orphaned containers from prior deploys were never removed and still hold the old image.
• Multiple tags / re-tags where another tag or a child image depends on the layers.
• Force-remove misconception. Users expect -f to override a running container’s hold — it does not.

Diagnostic Workflow

Find which containers reference the image. List running and all containers, then map them to the image:

docker ps                 # running
docker ps -a              # includes stopped
docker images

Show every container (running or not) built on that specific image:

docker ps -a --filter ancestor=5d0da3dc9764

Once you know the dependent container, stop and remove it — or force-remove it in one step:

docker rm -f 3f9ac1b2e7d4

With no container referencing the image anymore, remove the image:

docker rmi 5d0da3dc9764
docker images | grep myapp

If you only wanted to clean up old, unreferenced images in bulk:

docker image prune -a

Example Root Cause Analysis

A deployment script pulled registry.example.com/myapp:1.4.2, started it, and then tried to reclaim space by deleting the previous image tag registry.example.com/myapp:1.4.1:

docker rmi registry.example.com/myapp:1.4.1

It failed: conflict: unable to delete ... image is being used by running container. The new version had been started with docker run under a fixed name, but the old container from 1.4.1 had never been removed during the previous rollout — the script only ran docker stop, not docker rm. The stopped-then-restarted old container was actually still running because a restart policy had brought it back up.

docker ps -a --filter ancestor=registry.example.com/myapp:1.4.1 revealed the lingering container. The fix was to docker rm -f that old container first, then docker rmi registry.example.com/myapp:1.4.1 succeeded. The script was updated to always remove the previous container (not just stop it) before attempting to delete its image, making cleanup reliable across rollouts.

Prevention Best Practices

• Remove containers before images. Deploy scripts should docker rm -f the old container, then docker rmi the old image.
• Use --filter ancestor=<image> to find every dependent container before deleting an image.
• Prune with intent. docker container prune first, then docker image prune -a, so no orphan pins an image you want gone.
• Understand -f limits. docker rmi -f cannot remove an image held by a running container; stop/remove the container instead.
• Tag deliberately and clean old tags as part of each rollout so unused images do not accumulate. See the Docker stack guides.

Quick Command Reference

# Which containers use this image?
docker ps -a --filter ancestor=<image>

# Remove the dependent container (running or stopped)
docker rm -f <container>

# Now remove the image
docker rmi <image>

# Bulk-clean unreferenced images
docker image prune -a

Conclusion

image is being used by running container means a container still sits on top of the image’s layers, and (cannot be forced) means a running container’s hold cannot be overridden with -f. Use docker ps -a --filter ancestor=<image> to find the dependent container, docker rm -f it, then docker rmi the image. Ordering cleanup as containers-first, images-second keeps this conflict out of your deploys.