19.1.5 Rmi CLI Command

The docker rmi command removes one or more Docker images from the local image store. It frees disk space occupied by image layers and associated metadata. The command operates on images identified by their name, tag, or image ID, and it only removes an image if no running or stopped containers are currently using it.

Basic Syntax

docker rmi [OPTIONS] IMAGE [IMAGE...]

Multiple images can be removed in a single invocation by providing their names or IDs space-separated.

Removing an Image by Name and Tag

docker rmi myapp:1.0.0

This removes the image tagged 1.0.0 from the myapp repository. If other tags point to the same image manifest, those tags still exist — only the specified tag is removed. The underlying layers are deleted only when no remaining tags reference them.

Removing an Image by ID

docker rmi a1b2c3d4e5f6

Short or full image IDs can be used. If multiple tags reference the same image ID and you attempt to remove by ID, Docker refuses with an error unless all tags are removed first or the --force flag is used.

Removing Multiple Images at Once

docker rmi myapp:1.0.0 myapp:1.1.0 nginx:alpine

Each image is processed in order. If one removal fails (e.g., a container is using it), Docker reports the error and continues attempting the remaining removals.

Checking What Images Exist

Before removing, it is useful to list images:

docker images

Output:

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
myapp        1.0.0     a1b2c3d4e5f6   2 days ago     180MB
myapp        latest    a1b2c3d4e5f6   2 days ago     180MB
nginx        alpine    b3c2d1a0e9f8   5 days ago     23MB

Available Options

Force Removal

By default, docker rmi refuses to remove an image that is referenced by a stopped container, because the container would become unusable. The --force flag overrides this protection:

docker rmi --force myapp:1.0.0

Force removal untags the image and removes its layers even if stopped containers reference it. Those containers are now orphaned — their base image is gone, and running them again would fail.

Dangling Images

A dangling image is an untagged image that is no longer referenced by any tag. These accumulate after repeated builds that overwrite a tag. Dangling images show up as <none>:<none> in docker images:

docker images

REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
<none>       <none>    7f8e9d0c1b2a   3 hours ago   210MB

To remove all dangling images:

docker rmi $(docker images -f "dangling=true" -q)

Or using the prune subcommand:

docker image prune

Removing All Unused Images

To remove all images that are not referenced by any container (stopped or running):

docker image prune -a

This is more aggressive than removing dangling images — it removes any image with no active container reference, including tagged images that have simply never been run.

Relationship Between Tags and Layers

When an image has multiple tags, removing one tag does not delete the underlying layers. The layers are only deleted when the last tag referencing them is removed.

Removing myapp:latest only removes the tag pointer. The manifest and layer storage remain as long as myapp:1.0.0 still references them.

Removing Images in Bulk with Filters

Remove all images from a specific repository:

docker rmi $(docker images myapp -q)

Remove all images older than 48 hours:

docker image prune -a --filter "until=48h"

Remove images with a specific label:

docker image prune --filter "label=env=staging"

Error: Image is in Use by a Container

If a container (running or stopped) uses the image, the removal fails:

Error response from daemon: conflict: unable to remove repository reference "myapp:1.0.0" (must force) - container abc123def456 is using its referenced image a1b2c3d4e5f6

To resolve this, remove the container first:

docker rm abc123def456
docker rmi myapp:1.0.0

Or, if the container is running, stop it first:

docker stop abc123def456
docker rm abc123def456
docker rmi myapp:1.0.0

Scripting Cleanup Workflows

A common maintenance script that removes stopped containers and their associated images:

# Remove stopped containers
docker container prune -f

# Remove dangling images
docker image prune -f

# Remove unused images not referenced by any container
docker image prune -a -f

The -f flag suppresses the confirmation prompt, making the script fully non-interactive.