19.1.5.5 Rmi Disk Recovery

Disk recovery in the context of docker rmi refers to the practice of removing Docker images to reclaim storage space on the host machine. Docker's local image store accumulates data over time as images are pulled, built, and rebuilt. Without regular cleanup, the store can grow to tens or hundreds of gigabytes, particularly on build machines and developer workstations.

Auditing Current Disk Usage

Before removing images, it is useful to understand how much disk Docker is currently consuming:

docker system df

Output:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          18        4         4.73GB    3.91GB (82%)
Containers      7         2         412MB     310MB (75%)
Local Volumes   6         3         1.2GB     480MB (40%)
Build Cache     0         0         1.1GB     1.1GB

The RECLAIMABLE column shows how much can be freed. In this example, nearly 4 GB of the image store can be recovered by removing images that are no longer in active use.

For a more detailed breakdown per image:

docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

Removing Specific Images to Recover Space

When a large image is no longer needed, targeted removal is the most precise approach:

docker rmi tensorflow/tensorflow:2.12.0-gpu

Large images (machine learning frameworks, database images, build environments) can occupy several gigabytes each. Removing a single such image often recovers more space than dozens of smaller application images.

Recovering Space from Dangling Images

Dangling images are the easiest and safest targets for disk recovery. They are guaranteed to have no active container references and no child image dependencies:

docker image prune -f

Output:

Deleted Images:
deleted: sha256:a1b2c3d4e5f6...
deleted: sha256:9e8d7c6b5a4f...
deleted: sha256:...

Total reclaimed space: 1.84GB

On a busy build machine running repeated docker build commands, dangling images alone can accumulate gigabytes of waste within days.

Recovering Space from All Unused Images

When dangling cleanup is not sufficient, removing all images that no running or stopped container depends on frees significantly more space:

docker image prune -a -f

This removes all locally stored images that have no container reference, including tagged images that were pulled or built but never used to start a container.

Recovering Space from Stopped Containers First

Stopped containers prevent the removal of their associated images. A two-step recovery workflow first removes stopped containers, then removes images:

# Remove all stopped containers
docker container prune -f

# Remove all dangling images
docker image prune -f

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

After the first step, images that were previously blocked by stopped containers become reclaimable.

System-Wide Recovery in One Command

For maximum disk recovery in non-production environments:

docker system prune -a -f

This removes in one pass:

• All stopped containers
• All networks not used by containers
• All dangling images
• All images without containers (-a)
• The build cache

Output example:

Deleted Containers:
7f8e9d0c1b2a
...

Deleted Images:
untagged: myapp:1.0.0
deleted: sha256:...
...

Total reclaimed space: 6.3GB

Including Volumes

Volumes are not removed by default because they may contain persistent data. To include them:

docker system prune -a --volumes -f

This also removes all volumes not attached to running containers. Use this only when data in those volumes is no longer needed.

Recovering Space with Filters

To limit recovery to images matching specific criteria, filters narrow the scope:

Remove images older than 7 days:

docker image prune -a --filter "until=168h" -f

Remove images labeled as staging builds:

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

Checking the Effect of a Removal Before Committing

Docker does not have a dry-run mode for rmi, but inspecting images before removing them gives a clear picture of what will be deleted:

docker images --filter "dangling=true"

docker images --filter "until=72h"

Reviewing this output before running prune prevents accidentally removing images that are still needed.

Layer Deduplication and Actual Recovered Space

Because Docker uses content-addressable, deduplicated layer storage, the reclaimed space after removing an image is not always equal to its reported SIZE. If another image shares some of the same layers, those shared layers are not deleted, and the actual recovery is less than the image's total reported size.

For example, if two 500 MB images share a 400 MB base layer, removing one of them only reclaims the 100 MB of layers unique to that image, not the full 500 MB.

docker system df accounts for this deduplication and shows the true reclaimable amount rather than the sum of image sizes.

CI/CD Pipeline Disk Recovery

On ephemeral CI runners, disk space fills up quickly from successive build jobs. A post-build cleanup step in the pipeline prevents disk exhaustion:

# After tests and push are complete:
docker image prune -f
docker builder prune -f

For persistent runners (runners that handle multiple jobs sequentially), a more aggressive cleanup between jobs ensures consistent available space:

docker system prune -f

This keeps the runner healthy without manual intervention from the infrastructure team.