docker rmi refuses to delete an image because a stopped container uses it
image is being used by stopped containerShort answer
Docker keeps stopped containers until you remove them, and each one still points at the image it was created from. Removing the image fails while any container, running or stopped, refers to it. List the containers built from that image, remove them, then remove the image. If the image has several tags, remove by tag, not by ID.
Fix it fast
1Find out which cause you have
List every container, including stopped ones, that was created from the image. The IDs it prints are what block the removal.
docker ps -a --filter ancestor=myimage:1.02Match what you see, then jump to its fix
- 1
The error names a stopped container IDOne or more stopped containers still reference the imageFix - 2
docker ps -a lists a long tail of exited containers from earlier runsMany old stopped containers exist and you want them all goneFix - 3
The message says the image is tagged in multiple repositoriesThe image ID carries several tagsFix - 4
docker ps (without -a) shows a container from that imageA running container uses the imageFix
- 1
What does the error look like?
image is being used by stopped containerConflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
Cause 1 of 4
One or more stopped containers still reference the image
1Check
docker ps hides stopped containers unless you add -a. The ancestor filter matches containers created from a given image.
docker ps -a --filter ancestor=myimage:1.0 --filter status=exited2Fix
Remove the stopped containers you do not need, then remove the image. Add -v only if you also want their anonymous volumes gone.
docker rm <container-id>
docker rmi myimage:1.03Verify
The image no longer appears in the image list.
docker image ls myimageConfirmed by docs.docker.com
Cause 2 of 4
Many old stopped containers exist and you want them all gone
1Check
docker container prune removes every stopped container, or only those matching a filter such as an age. It asks for confirmation first.
docker ps -a --filter status=exited -q | wc -l2Fix
Prune the stopped containers, then remove the image. Use the until filter to keep recent ones.
docker container prune --filter "until=24h"
docker rmi myimage:1.03Verify
Run the removal again; it succeeds without a conflict.
docker image lsConfirmed by docs.docker.com
Cause 3 of 4
The image ID carries several tags
1Check
Removing by ID fails when the image has more than one tag. Removing by tag only untags that name.
docker image ls --no-trunc | grep fd484f19954f2Fix
Remove each tag by name. Use -f with the ID only if you want every tag and the image deleted in one step.
docker rmi myimage:1.0
docker rmi myimage:latest3Verify
List images again and check the ID is gone.
docker image lsConfirmed by docs.docker.com
Cause 4 of 4
A running container uses the image
1Check
A running container needs -f on docker rmi, and the image stays in use until the container stops.
docker ps --filter ancestor=myimage:1.02Fix
Stop and remove the container first. Forcing removal of the image is possible, but stop the container so you do not lose work in it.
docker stop <container-id>
docker rm <container-id>
docker rmi myimage:1.03Verify
The remove command succeeds and the image is gone from the list.
docker image ls myimageConfirmed by docs.docker.com
How do I stop it coming back?
- Start throwaway containers with docker run --rm so they delete themselves when they stop.
- Run docker container prune on a schedule on build servers.
- Refer to images by tag in scripts, not by ID.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
A dev container port does not open in the browser when Docker runs on a remote host
If your application only accepts calls from localhost, it will reject connections from published ports
Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.
3 causes, each with a fix