How to fix 'conflict: unable to delete repository reference' (image in use)

What this error means

You tried to remove a Docker image (or tag) that is still referenced. Common causes:

• A running or stopped container uses the image.
• The image has multiple tags; you’re deleting one while others still reference the same digest.
• A child image depends on the parent you’re trying to remove (less common).

Typical message:

Error response from daemon: conflict: unable to delete repository reference
(image is being used by running container)

Quickstart (most cases)

1. Find containers using the image:

docker ps -a --filter ancestor=REPO:TAG --format '{{.ID}} {{.Image}} {{.Status}}'

1. Stop and remove them:

docker stop $(docker ps -q --filter ancestor=REPO:TAG)
# Remove both running and exited that match the image
docker rm $(docker ps -aq --filter ancestor=REPO:TAG)

1. Remove the image (and any remaining tags for that digest):

docker image rm REPO:TAG

If you still see a conflict, list and remove all tags pointing to the same image ID (see “Multiple tags” below).

Minimal working example

This creates the error and shows the fix.

# 1) Run a container from alpine
docker run -d --name demo alpine:3.19 sleep 1000

# 2) Try to remove the image (will fail)
docker image rm alpine:3.19
# -> conflict: image is being used by running container

# 3) Stop and remove the container
docker stop demo && docker rm demo

# 4) Remove the image (succeeds)
docker image rm alpine:3.19

Step-by-step resolution

1. Identify by image ID to avoid ambiguity

docker image ls --digests | grep REPO
# Or get ID directly
docker image inspect REPO:TAG --format '{{.Id}}'

1. Find all containers using the image

docker ps -a --filter ancestor=IMAGE_ID --format '{{.ID}} {{.Image}} {{.Status}}'

• If any exist: stop then remove them.

docker stop $(docker ps -q --filter ancestor=IMAGE_ID)
docker rm $(docker ps -aq --filter ancestor=IMAGE_ID)

1. Remove all tags referencing the same digest

• List tags for the image:

docker image inspect IMAGE_ID --format '{{join .RepoTags "\n"}}'

• Remove each tag explicitly:

# Example; replace with your tags
docker image rm repo1/name:tag1 repo1/name:tag2

1. Handle child-image dependency conflicts If you see “image has dependent child images”, remove child images first:

docker image ls --filter since=IMAGE_ID
# Remove specific child images by tag or ID
docker image rm CHILD_IMAGE_ID ...

1. Last resort: force removal Only if you understand the impact and have removed containers.

docker image rm -f IMAGE_ID

Multiple tags and digests

A single image digest can have several tags. Deleting one tag only untags it; the image content remains if other tags still point to it.

• Show all tags that reference the same ID:

ID=$(docker image inspect REPO:TAG --format '{{.Id}}')
docker image inspect "$ID" --format '{{join .RepoTags "\n"}}'

• Remove all those tags, then remove the image by ID:

docker image rm $(docker image inspect "$ID" --format '{{join .RepoTags " "}}') || true
docker image rm "$ID"

With Docker Compose

If containers were started by Compose, use Compose to stop and clean up:

# In the project directory
docker compose down --rmi local --volumes --remove-orphans

• --rmi local removes images built by the compose project (not pulled ones).
• Then remove remaining images by tag or ID as needed.

Quick reference table

Pitfalls and safe practices

• Using ancestor filter can match more than you think. Double-check with docker ps -a before removal.
• docker image rm by tag may only untag; remove by ID to ensure deletion after all tags are gone.
• Avoid docker system prune -a unless you’re certain; it removes all unused images, containers, networks, and build cache.
• Don’t force-remove images in active environments; running services may crash on next restart if their image is missing.

Performance notes

• Prefer bulk operations with care:

# Stop/remove all containers using an image in parallel
ID=$(docker image inspect REPO:TAG --format '{{.Id}}')
docker ps -aq --filter ancestor=$ID | xargs -r -n1 -P4 docker rm -f

• When cleaning many unused images, use filters to narrow scope, reducing daemon work:

# Remove dangling (untagged) images only
docker image prune -f
# Remove unused images from a specific repository
docker image ls 'myrepo/*' -q | xargs -r docker image rm

• Compose cleanup can be faster than manual per-container operations for stacks:

docker compose down --rmi local --volumes

Troubleshooting checklist

1. Is any container (running or exited) using the image?
2. Are there other tags pointing to the same image ID?
3. Are there child images? Remove them first.
4. Are you in the correct Docker context/host? (docker context ls)
5. Still stuck? Try removing by ID and use -f only after stopping containers.

FAQ

Q: Why does docker rmi repo:tag not delete the image? A: It may only remove that tag. If other tags reference the same digest, the image is still present. Remove all tags or delete by image ID.

Q: How do I find what’s using the image? A: Use docker ps -a --filter ancestor=IMAGE_ID. This lists containers created from that image.

Q: Do volumes or networks block image deletion? A: No. Only containers or image references (tags/child images) block deletion. Volumes/networks can be removed independently.

Q: Is docker image rm -f safe? A: It force-untags and removes images even if referenced (not by running containers). Use only when you’ve confirmed it won’t break services.