docker rmi conflict - unable to remove repository reference, container is using its referenced image (every docker rm and rmi conflict fixed, with real output)

TL;DR

• conflict: unable to remove repository reference ... container <id> is using its referenced image means a container still points at that image. Remove the container first, then the image: docker rm -f <container> and docker rmi <image>.
• Stopped containers count too. docker ps shows nothing, but docker ps -a --filter ancestor=<image> shows the Exited container that pins it. docker container prune -f removes every stopped container in one go.
• image is referenced in multiple repositories means you removed by image ID and the ID has several names. Remove each repo:tag, or use docker rmi -f <id>.
• image has dependent child images (cannot be forced) cannot be fixed with -f at all - remove the child image first.
• docker rmi -f on the image of a running container does not delete anything. It only removes the tag; the 48.2 MB of layers stay behind as <none>:<none> until the container is gone and docker image prune -f runs.
• Every output below is from Docker 28.0.4 on Ubuntu 24.04, captured on 2026-10-14.
• Not your exact case? The closest post on this site is docker restart container.

I wrote the first version of this post in 2021, after I filled the disk of a build server with old images and docker rmi refused to delete half of them. The fix I gave then (prune everything) works, but it is a sledgehammer. In October 2026 I went back and reproduced every conflict docker rm and docker rmi can throw, one by one, on a clean Docker 28.0.4 machine, so you can match your exact error text to its cause and fix only that.

Table of Content

1. The six conflicts at a glance
2. Container is using its referenced image
3. Container is running
4. The container name is already in use
5. A stopped container still pins the image
6. Image is referenced in multiple repositories
7. Image has dependent child images (cannot be forced)
8. What docker rmi -f really does
9. Cleaning up in bulk - prune and system df
10. What broke when I ran this
11. Conclusion

1. The six conflicts at a glance

The rule behind all six: Docker deletes image layers only when nothing points at them any more - no container, no tag, no child image. Every conflict is Docker telling you which pointer is still there.

2. Container is using its referenced image

This is the error most people search for. I started an nginx container and then tried to remove its image:

1$ docker run -d --name web nginx:1.27-alpine
23f890a5103ddcfbf56e01df7e362c2bcc1f52baefe65fa05d4fa8b1c41426ec3
3
4$ docker rmi nginx:1.27-alpine
5Error response from daemon: conflict: unable to remove repository reference "nginx:1.27-alpine" (must force) - container 3f890a5103dd is using its referenced image 6769dc3a703c

The message gives you both IDs: the container (3f890a5103dd) and the image (6769dc3a703c). The fix is to remove the container, then the image:

1$ docker rm -f web
2web
3
4$ docker rmi nginx:1.27-alpine
5Untagged: nginx:1.27-alpine
6Untagged: nginx@sha256:65645c7bb6a0661892a8b03b89d0743208a18dd2f3f17a54ef4b76fb8e2f2a10
7Deleted: sha256:6769dc3a703c719c1d2756bda113659be28ae16cf0da58dd5fd823d6b9a050ea
8Deleted: sha256:61b1a4867a5ae766114a788e5bd5422883ed50a376763f2c623da4222aba2d81
9...

This time you get Deleted lines - nine of them for this image. When you only see Untagged and no Deleted, the image still has another name or a container, and nothing was freed.

If you do not know which containers use an image, ask Docker directly:

1docker ps -a --filter ancestor=nginx:1.27-alpine

3. Container is running

docker rm refuses a running container:

1$ docker rm web
2Error response from daemon: cannot remove container "/web": container is running: stop the container before removing or force remove

Two ways out. docker stop web && docker rm web gives the process the normal shutdown window (SIGTERM, then SIGKILL after 10 seconds by default). docker rm -f web sends SIGKILL straight away - fine for a throwaway container, not for a database in the middle of a write. The docker container rm reference lists both, plus -v to remove the container's anonymous volumes in the same step.

4. The container name is already in use

This one is a docker run error, but it lands on this page because the fix is a removal:

1$ docker run -d --name web nginx:1.27-alpine
2docker: Error response from daemon: Conflict. The container name "/web" is already in use by container "3f890a5103ddcfbf56e01df7e362c2bcc1f52baefe65fa05d4fa8b1c41426ec3". You have to remove (or rename) that container to be able to reuse that name.

Container names are unique per Docker host, including exited containers. So docker ps can show nothing while the name is still taken. docker ps -a --filter name=web finds it; docker rm -f web frees the name. In scripts I run containers with --rm so the name is released the moment the container exits.

5. A stopped container still pins the image

This is the case that confuses people, because docker ps is empty. I ran a one-shot container that exits immediately:

1$ docker run --name once nginx:1.27-alpine nginx -v
2nginx version: nginx/1.27.5
3
4$ docker rmi nginx:1.27-alpine
5Error response from daemon: conflict: unable to remove repository reference "nginx:1.27-alpine" (must force) - container 5bcf444d4546 is using its referenced image 6769dc3a703c
6
7$ docker ps -a --filter ancestor=nginx:1.27-alpine --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'
8CONTAINER ID   NAMES     STATUS
95bcf444d4546   once      Exited (0) Less than a second ago

An exited container keeps its filesystem layer on top of the image, so the image cannot go. docker container prune -f removes all stopped containers at once:

 1$ docker container prune -f
 2Deleted Containers:
 35bcf444d4546abf013ad415737b780d5e456282b7e57a52bf7d2ea581d8524a1
 4
 5Total reclaimed space: 1.093kB
 6
 7$ docker rmi nginx:1.27-alpine
 8Untagged: nginx:1.27-alpine
 9...
10Deleted: sha256:6769dc3a703c719c1d2756bda113659be28ae16cf0da58dd5fd823d6b9a050ea

Be careful with prune on a shared machine: it removes every stopped container, including ones somebody stopped on purpose and wanted to start again. The docker container prune reference shows --filter "until=24h" to keep recent ones.

6. Image is referenced in multiple repositories

One image ID can carry many names. I gave alpine two more tags, then tried to remove it by ID:

 1$ docker tag alpine:3.20 myrepo/alpine:base
 2$ docker tag alpine:3.20 registry.example.com/team/alpine:base
 3$ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
 4REPOSITORY                                   TAG       IMAGE ID
 5alpine                                       3.20      bf8527eb54c3
 6myrepo/alpine                                base      bf8527eb54c3
 7registry.example.com/team/alpine             base      bf8527eb54c3
 8
 9$ docker rmi bf8527eb54c3
10Error response from daemon: conflict: unable to delete bf8527eb54c3 (must be forced) - image is referenced in multiple repositories

Docker protects you from deleting three names with one ID by accident. Remove the extra names explicitly - this only untags, nothing is deleted while one name remains:

1$ docker rmi myrepo/alpine:base registry.example.com/team/alpine:base
2Untagged: myrepo/alpine:base
3Untagged: registry.example.com/team/alpine:base

docker rmi -f bf8527eb54c3 would have removed all three names and the layers in one go. That is the same mechanism as renaming an image, which I covered in how to rename a Docker image.

7. Image has dependent child images (cannot be forced)

The classic builder keeps an intermediate image for every RUN step, and each one is the parent of the next. Trying to remove a parent fails, and this is the one conflict where force does not help:

1$ docker rmi sha256:6b739e2b9dfde8063ebfa0e14dfe627e23cf836995052bbde0766494a0500cdc
2Error response from daemon: conflict: unable to delete 6b739e2b9dfd (cannot be forced) - image has dependent child images
3
4$ docker rmi -f sha256:6b739e2b9dfde8063ebfa0e14dfe627e23cf836995052bbde0766494a0500cdc
5Error response from daemon: conflict: unable to delete 6b739e2b9dfd (cannot be forced) - image has dependent child images

Remove the child (the tagged image you actually built) and the parents go with it:

1$ docker rmi legacy:1
2Untagged: legacy:1
3Deleted: sha256:5d85329adf5a305903c6d4e2071ff66facd3df981d6f02ff8dd1f5b210c86192
4Deleted: sha256:6468a1787578438cec19fcf11f8c0400129e3640580b622bb7d74cb187feb58b
5Deleted: sha256:6b739e2b9dfde8063ebfa0e14dfe627e23cf836995052bbde0766494a0500cdc
6Deleted: sha256:686eb26bb9e1cc53a65ee06eea359c2cb7bdbb8fd912f5c33ce8dbeed43098c2

You only meet this on images built with the legacy builder (DOCKER_BUILDKIT=0) or very old Docker versions. BuildKit, the default builder since Docker 23.0, does not store intermediate images in the image list.

8. What docker rmi -f really does

Many answers say "just add -f". Here is what that does to the image of a running container:

 1$ docker run -d --name web2 nginx:1.27-alpine
 2525f1950cabcec1631f0c654cd85a3e10d0a4e83b64cef9460669f12679888b7
 3
 4$ docker rmi -f nginx:1.27-alpine
 5Untagged: nginx:1.27-alpine
 6Untagged: nginx@sha256:65645c7bb6a0661892a8b03b89d0743208a18dd2f3f17a54ef4b76fb8e2f2a10
 7
 8$ docker ps --filter name=web2 --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
 9NAMES     IMAGE          STATUS
10web2      6769dc3a703c   Up Less than a second
11
12$ docker images --filter dangling=true --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Size}}'
13REPOSITORY   TAG       IMAGE ID       SIZE
14<none>       <none>    6769dc3a703c   48.2MB

The container keeps running, the image loses its name, and all 48.2 MB stay on disk as a dangling <none>:<none> image. The IMAGE column of docker ps now shows a bare ID, which makes it harder to tell later which version that container runs. The docker image rm reference describes -f as removing the image even if it is in use, but in practice it removes the reference; the layers can only go once the container does.

9. Cleaning up in bulk - prune and system df

When the goal is disk space rather than one image, go in this order and check the result after each step:

1docker system df            # what is using space, and how much is reclaimable
2docker container prune -f   # stopped containers (unpins their images)
3docker image prune -f       # dangling <none>:<none> images only
4docker image prune -a -f    # every image not used by a container - re-pulls later

After removing my test container, docker image prune -f freed the dangling image from section 8:

 1$ docker image prune -f
 2Deleted Images:
 3deleted: sha256:6769dc3a703c719c1d2756bda113659be28ae16cf0da58dd5fd823d6b9a050ea
 4...
 5Total reclaimed space: 48.22MB
 6
 7$ docker system df
 8TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
 9Images          8         0         1.859GB   1.859GB (100%)
10Containers      0         0         0B        0B
11Local Volumes   0         0         0B        0B
12Build Cache     0         0         0B        0B

docker system prune does all of the above plus networks and build cache in one command; I keep it for throwaway machines. If you are here because the disk is already full, fixing "no space left on device" goes deeper into /var/lib/docker. The docker image prune reference has the filters (until, label) I use on CI runners.

10. What broke when I ran this

I ran all of this as one script on a fresh GitHub Actions runner (Ubuntu 24.04, Docker 28.0.4) on 2026-10-14. A few things did not go the way I expected.

1. My "image list" was full of images I never pulled. The first docker images on the runner listed ghcr.io/github/github-mcp-server, dependabot-updater-core and four others before my alpine rows. Hosted runners come pre-loaded, so docker system df reported 8 images and 1.859 GB before I had done anything. On your own laptop, check docker system df before and after a cleanup - the "before" number is often not what you think.

2. The dependent-child conflict was hard to reproduce on purpose. With BuildKit (the default), building a multi-step Dockerfile left no intermediate images, so there was no parent to conflict with. I had to build with the legacy builder (DOCKER_BUILDKIT=0) to get image has dependent child images. If you see this error on a modern Docker, you are almost certainly looking at images built years ago.

3. docker rmi -f "succeeded" and freed nothing. It printed two Untagged lines and exited 0, which reads like success. Only docker images --filter dangling=true showed the 48.2 MB still there. I now always follow a forced removal with docker system df.

4. A one-second-old exited container blocked the delete. docker run --name once nginx:1.27-alpine nginx -v ran for well under a second, and its Exited (0) container was enough to block docker rmi. That is the same reason --rm belongs on every one-shot docker run.

11. Conclusion

Every docker rm / docker rmi conflict is a pointer that still exists. To summarise what I found:

1. container ... is using its referenced image - remove the container (running or stopped) first, then the image.
2. container is running - docker stop then docker rm, or docker rm -f.
3. container name ... is already in use - an exited container owns the name; docker rm -f <name> or use --rm.
4. referenced in multiple repositories - untag each repo:tag, or docker rmi -f <id>.
5. dependent child images - remove the child; -f cannot help.
6. docker rmi -f on a running container's image only untags it; the space comes back after the container goes and docker image prune -f runs.

If the container you removed needs to come back with the same name, restarting a single Docker container covers restart versus recreate, and if your next error is about the image name itself, see docker: invalid reference format.