19.1.5.2 Rmi Force Removal

Force removal in docker rmi allows deleting an image even when Docker's default safety checks would normally block the operation. The standard docker rmi command refuses to remove images that are currently referenced by one or more containers, whether those containers are running or stopped. The --force flag overrides this refusal and proceeds with deletion.

The Default Behavior and Why It Blocks

Without --force, Docker checks whether any container has a reference to the image before proceeding. The check includes:

• Running containers
• Stopped containers
• Paused containers

If any container references the image, the command fails:

docker rmi myapp:2.0.0

Error response from daemon: conflict: unable to remove repository reference "myapp:2.0.0" (must force) - container 9b8a7c6d5e4f is using its referenced image d4f3e2c1b0a9

The error message names the conflicting container ID and the image ID, which helps identify what needs to be cleaned up first.

Using the Force Flag

docker rmi --force myapp:2.0.0

Or the short form:

docker rmi -f myapp:2.0.0

Force removal proceeds in two steps:

1. All tags pointing to the image are removed (untagged).
2. The image layers are deleted from the local store.

What Force Removal Does and Does Not Do for Running Containers

Force removal does not interrupt or kill running containers. A running container has an active union filesystem mounted on top of the image layers. The operating system holds those layers open (similar to how a deleted file on Linux remains accessible until all file handles to it are closed).

Docker marks the layers for deletion but defers the physical deletion until all containers using them have been stopped and removed. After force removal:

• Running containers continue to operate normally.
• Pulling or running the same image again requires re-downloading it, because the tag no longer exists locally.
• Once the running container stops and is removed, the marked layers are cleaned up.

Impact on Stopped Containers

Stopped containers that referenced the force-removed image are left in a broken state. Their metadata still records the image ID, but the image no longer exists locally. Attempts to start such a container will fail:

docker start 9b8a7c6d5e4f

Error response from daemon: No such image: d4f3e2c1b0a9

The container entry still appears in docker ps -a, but it cannot be restarted without pulling the image again.

Force Removal of Multiple Tags Pointing to the Same Image

When multiple tags reference the same image ID and you force-remove by ID, Docker removes all tags at once:

docker rmi --force d4f3e2c1b0a9

Output:

Untagged: myapp:2.0.0
Untagged: myapp:latest
Deleted: sha256:d4f3e2c1b0a9...
Deleted: sha256:...

This is more efficient than removing each tag individually and avoids the "image is referenced by multiple tags" error that would appear without force.

Force Removal vs. Proper Container Cleanup

Force removal is a shortcut. The recommended workflow is to clean up containers before removing images, which is safer and produces no orphaned containers:

# Stop the container
docker stop 9b8a7c6d5e4f

# Remove the container
docker rm 9b8a7c6d5e4f

# Now rmi succeeds without force
docker rmi myapp:2.0.0

Force removal is most useful in scenarios where:

• Automation needs to clean up quickly without tracking container IDs.
• Containers from a previous test run were not removed and are no longer needed.
• A build pipeline rebuilds images repeatedly with the same tag and wants to ensure old layers are reclaimed.

Force in Batch Operations

In scripted workflows, force is commonly combined with bulk operations:

# Force-remove all images with a specific name
docker rmi --force $(docker images myapp -q)

# Force-remove all images (dangerous — removes everything)
docker rmi --force $(docker images -q)

The second form removes all local images regardless of container references. It should only be used on development machines or ephemeral CI environments where all containers are intentionally discarded.

The --no-prune Option

By default, docker rmi also deletes intermediate (parent) layers that are no longer referenced after the removal. The --no-prune flag prevents this:

docker rmi --force --no-prune myapp:2.0.0

This is rarely needed in practice. It can be useful when intermediate layers are shared with another image that is still present, or when debugging layer references manually.

Summary of Behavior