Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker rmi refuses to delete an image because a stopped container uses it

Errorimage is being used by stopped container

Short 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.

  • Applies to Docker Engine 28, Docker CLI 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.0
  2. 2Match what you see, then jump to its fix

    1. 1The error names a stopped container IDOne or more stopped containers still reference the imageFix
    2. 2docker ps -a lists a long tail of exited containers from earlier runsMany old stopped containers exist and you want them all goneFix
    3. 3The message says the image is tagged in multiple repositoriesThe image ID carries several tagsFix
    4. 4docker ps (without -a) shows a container from that imageA running container uses the imageFix

What does the error look like?

  • image is being used by stopped container
  • Conflict, 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=exited

2Fix

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.0

3Verify

The image no longer appears in the image list.

docker image ls myimage

Confirmed by docs.docker.com

Did this fix it?

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 -l

2Fix

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.0

3Verify

Run the removal again; it succeeds without a conflict.

docker image ls

Confirmed by docs.docker.com

Did this fix it?

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 fd484f19954f

2Fix

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:latest

3Verify

List images again and check the ID is gone.

docker image ls

Confirmed by docs.docker.com

Did this fix it?

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.0

2Fix

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.0

3Verify

The remove command succeeds and the image is gone from the list.

docker image ls myimage

Confirmed by docs.docker.com

Did this fix it?

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

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.