19.1.5.1 Rmi Local Image Removal

Local image removal refers to deleting Docker images that have been downloaded, built, or tagged on the current machine. Docker stores all images in a local image store managed by the Docker daemon. Over time this store grows as new images are pulled or built, and removing images that are no longer needed reclaims disk space without affecting any remote registry.

Where Docker Stores Images

Docker's local image store is located in the Docker data directory, which defaults to:

• Linux: /var/lib/docker/
• macOS / Windows (Docker Desktop): Inside the Docker Desktop virtual machine's filesystem

The structure is content-addressable: image layers are stored as blobs identified by their SHA256 digest. Tags are stored separately as mutable pointers to manifest digests.

Viewing the Local Image Store

docker images

Output:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
myapp         2.0.0     d4f3e2c1b0a9   1 hour ago     245MB
myapp         1.5.0     a1b2c3d4e5f6   3 days ago     238MB
nginx         latest    b3c2d1a0e9f8   1 week ago     142MB
postgres      15        f9e8d7c6b5a4   2 weeks ago    413MB
<none>        <none>    0a1b2c3d4e5f   5 days ago     241MB

The <none>:<none> entry is a dangling image — an untagged intermediate result of a previous build.

Removing a Specific Image by Tag

docker rmi myapp:1.5.0

Output:

Untagged: myapp:1.5.0
Deleted: sha256:a1b2c3d4e5f6...
Deleted: sha256:...  (intermediate layers)

Each Deleted: line represents a content-addressed layer being removed from the local store. If another image shares some of those layers (for example, myapp:2.0.0 was built on the same base), those shared layers are retained and only the unshared ones are deleted.

Removing by Image ID

When an image has no tag (dangling), it can be removed by its ID:

docker rmi 0a1b2c3d4e5f

Short IDs (first 12 characters) are accepted as long as they are unambiguous on the local machine. If the short ID matches more than one image, Docker reports an error and the full ID must be used.

Removing Multiple Images

docker rmi myapp:1.5.0 nginx:latest

Docker processes each removal in sequence. If any image fails (for example, it is used by a stopped container), Docker reports the error for that image but continues removing the others.

What Prevents Removal

A local image cannot be removed while any container — running or stopped — references it. Docker tracks these references internally.

Attempting removal while a stopped container uses the image:

docker rmi myapp:1.5.0

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

The solution is to remove the container first:

docker rm 4d3c2b1a0e9f
docker rmi myapp:1.5.0

Force Removal

The --force flag removes the image regardless of stopped container references:

docker rmi --force myapp:1.5.0

This untags the image and deletes the layers. Stopped containers that were referencing the image become orphaned — their image reference is broken. Running containers are not affected because Docker does not delete layers that an actively running container's file system overlay depends on; it marks them for deletion instead, deferring actual deletion until the container is stopped and removed.

Removing All Images

To remove every image currently stored locally:

docker rmi $(docker images -q)

docker images -q returns only the image IDs, which are then passed to rmi. This fails if any containers (running or stopped) reference images. A safer approach first removes all stopped containers:

docker container prune -f
docker rmi $(docker images -q)

Removing Dangling Images

Dangling images (<none>:<none>) are untagged images with no container references. They are the most common accumulation from iterative builds. Docker provides a dedicated command to remove all of them at once:

docker image prune

With -f to skip the confirmation prompt:

docker image prune -f

Removing All Unused Images

The -a flag extends pruning to all images not referenced by any container, not just dangling ones:

docker image prune -a

This is suitable for development machines where old versions of images have been superseded and containers from them no longer exist.

Filtering Images for Removal

Prune commands support filter expressions:

Remove images created more than 72 hours ago:

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

Remove images with a specific label:

docker image prune --filter "label=project=myapp"

Disk Impact

Each docker rmi invocation reports the total reclaimed space:

Total reclaimed space: 238.4MB

To audit disk usage before cleaning up:

docker system df

Output:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        3         2.14GB    1.83GB (85%)
Containers      5         2         123MB     98MB (79%)
Local Volumes   4         2         512MB     210MB (41%)
Build Cache     0         0         0B        0B

This shows how much disk is used and how much could be freed by removing unused resources.

Layer Sharing and Deletion Safety

Docker's layer sharing model means that removing an image never deletes a layer that is still needed by another image. The local store uses reference counting at the layer level. A layer is only physically deleted from disk when no remaining image manifest references it.

Removing myapp:1.5.0 deletes App Layer v1.5 but preserves Shared Base Layer because myapp:2.0.0 still depends on it.