Fixing Docker Error: "conflict: unable to remove repository reference"

Have you ever tried to clean up your local machine by deleting old Docker images, only to be met with this frustrating message?

Error response from daemon: conflict: unable to remove repository reference

"my-image" (must force) - container <ID> is using its referenced image <ID> 

This error happens because Docker is protective. It won't let you delete an image if there is a container—even a stopped one—that was created from it.

Step 1: Identify the "Zombie" Containers

The error message usually gives you a container ID. You can see all containers (running and stopped) that are blocking your deletion by running:

docker ps -a

Look for any container that is using the image you are trying to delete.

Step 2: Remove the Container First

Before you can delete the image, you must remove the container. If the container is still running, you’ll need to stop it first:

# Stop the container

docker stop <container_id>

# Remove the container 

docker rm <container_id>

Step 3: Delete the Image

Now that the dependency is gone, you can safely remove the image:

docker rmi <image_name_or_id>

The "Shortcut" (Force Delete)

If you don't care about the containers and just want the image gone immediately, you can use the -f (force) flag.

Warning: This will leave "dangling" containers that no longer have a valid image reference.

docker rmi -f <image_id>

Pro Tip: The Bulk Cleanup

If your machine is cluttered with dozens of these conflicts, don't fix them one by one. Use the prune command to safely remove all stopped containers and unused images in one go:

docker system prune

(Add the -a flag if you also want to remove unused images, not just "dangling" ones.)