19.1.5.4 Rmi Dependency Conflict

A dependency conflict in docker rmi occurs when Docker refuses to remove an image because another entity — a container, another image, or an active mount — still holds a reference to it. These conflicts arise from Docker's internal reference tracking system, which prevents accidental deletion of resources that are still in active use.

Types of Dependencies That Cause Conflicts

Container References

The most common source of conflicts is a container that was created from the image. This applies regardless of whether the container is currently running, stopped, paused, or in any other state.

docker rmi myapp:3.0.0

Error response from daemon: conflict: unable to remove repository reference "myapp:3.0.0" (must force) - container 7f8e9d0c1b2a is using its referenced image c3d4e5f6a7b8

The error identifies:

• The tag (myapp:3.0.0) that was requested for removal
• The container ID (7f8e9d0c1b2a) that holds the reference
• The underlying image ID (c3d4e5f6a7b8)

Child Image Dependencies

When image B is built using image A as its base (via FROM image_a in the Dockerfile), image A has a child dependency. Attempting to remove image A while image B still exists on the local machine will fail if the removal would result in breaking the child image's layer chain.

Docker tracks this relationship through the parent-child layer linkage. Each layer records a reference to its parent layer digest. When you try to remove a parent layer that is still used by a child image, Docker blocks the operation:

docker rmi ubuntu:22.04

Error response from daemon: conflict: unable to delete 1f6ddc1b2547 (cannot be forced) - image is being used by image 3a4b5c6d7e8f

This form of conflict uses the phrase "cannot be forced" — meaning even --force will not work, because the child image would be left in a broken state with missing layers.

Multiple Tags Pointing to the Same Image

When removing by image ID and multiple tags reference the same image, Docker refuses the removal without --force:

docker rmi c3d4e5f6a7b8

Error response from daemon: conflict: unable to delete c3d4e5f6a7b8 (must force) - image is referenced in multiple repositories

Each tag must be removed individually, or --force must be used to remove all tags and the image simultaneously.

Resolving Container Reference Conflicts

The safest resolution is to remove the conflicting container before removing the image.

First, find which container is blocking the removal:

docker ps -a --filter ancestor=myapp:3.0.0

CONTAINER ID   IMAGE          COMMAND       CREATED       STATUS                     NAMES
7f8e9d0c1b2a   myapp:3.0.0   "/app/run"    2 hours ago   Exited (0) 1 hour ago      myapp_v3

Stop the container if it is running:

docker stop 7f8e9d0c1b2a

Remove the container:

docker rm 7f8e9d0c1b2a

Now the image can be removed:

docker rmi myapp:3.0.0

Resolving Child Image Conflicts

To remove a base image that has dependent child images, the child images must first be removed:

# List all images to find child images of ubuntu:22.04
docker images

Identify images that were built on the conflicting base, then remove them in order from most derived to least:

docker rmi myapp:3.0.0       # child of ubuntu:22.04
docker rmi ubuntu:22.04      # now safe to remove

Conflicts That Cannot Be Forced

The --force flag resolves container reference conflicts and multiple-tag conflicts. It does not resolve child image dependency conflicts:

docker rmi --force ubuntu:22.04

Error response from daemon: conflict: unable to delete 1f6ddc1b2547 (cannot be forced) - image is being used by image 3a4b5c6d7e8f

The "cannot be forced" phrasing is Docker's way of indicating that this particular conflict requires resolving the dependency before proceeding, regardless of flags.

Discovering All References to an Image

To identify everything that depends on a specific image:

Find containers using an image by name:

docker ps -a --filter ancestor=ubuntu:22.04

Find containers using an image by ID:

docker ps -a --filter ancestor=1f6ddc1b2547

There is no built-in command to list child images directly, but the following approach works:

docker inspect --format='{{.Id}} {{.Parent}}' $(docker images -q) | grep 1f6ddc1b2547

This lists all image IDs whose parent field matches the target image ID, revealing the direct children.

Conflict Resolution Order

When multiple dependency types are present, remove them in this order:

1. Stop running containers that use the image or its children.
2. Remove stopped containers that use the image or its children.
3. Remove child images (starting from the most derived).
4. Remove the target image.

Following this order avoids encountering new conflicts at each step and ensures that each removal succeeds without the need for force.