19.1.2.5 Images Size Column

The images size column reports an image's total, virtual size, including every layer it references, even layers genuinely shared with other images on the same host, which means summing this column across multiple images significantly overstates actual total disk consumption, a distinction worth understanding precisely before drawing any conclusion about real, exclusive disk usage from this value alone.

What the displayed size actually includes

The size shown for a given image includes the combined size of every layer it is built from, regardless of whether some of those layers are also shared with, and already counted toward, a different image's own reported size:

docker images

REPOSITORY   TAG       SIZE
my-api       1.4.2     180MB
my-worker    1.2.0     175MB

If both of these images share the same base layer, a sizable chunk of each reported figure represents identical, physically shared content stored only once on disk, not duplicated storage corresponding to the full sum of both numbers, which means naively adding these two figures together would significantly overstate how much disk space removing both images would actually reclaim.

Why naive summation overstates total usage

docker images --format "{{.Size}}"

Summing this column across every listed image produces a number considerably larger than the host's actual total Docker disk usage whenever any meaningful layer sharing exists between images, which is almost always the case for any set of images built from a common or related base:

docker system df

TYPE      TOTAL   SIZE
Images    12      1.2GB

Comparing this aggregate, deduplicated total against the naive sum of individual image sizes reveals exactly how much the naive approach overstates actual usage, which is a useful, concrete way to demonstrate the difference directly rather than relying on the conceptual explanation alone.

Format fields distinguishing different size concepts

Beyond the default Size field, docker images --format exposes related but distinct fields specifically useful for understanding shared versus unique contribution:

docker system df -v

IMAGE          SHARED SIZE   UNIQUE SIZE   TOTAL SIZE
my-api:1.4.2   140MB         40MB          180MB

The verbose system df output specifically breaks an image's total size into its shared portion (layers also used by other images) and its unique portion (layers genuinely exclusive to this specific image), which is considerably more useful than the plain images listing's single combined figure when the actual question is "how much space would removing this specific image genuinely reclaim."

Estimating actual reclaimable space correctly

The unique size figure, not the total size figure, is the accurate answer to how much disk space removing a specific image would actually free, since removing an image never affects layers still referenced by another, remaining image:

docker rmi my-api:1.4.2
df -h

If my-worker still references the shared base layer my-api also used, removing my-api alone frees only its unique portion, not its full, reported total size; the shared layers remain on disk for as long as any other image still references them.

Why this matters for cleanup prioritization

When deciding which images to remove first to address genuine disk pressure, prioritizing by unique size rather than total size targets actual, reclaimable space more effectively, since an image with a large total size but mostly shared layers reclaims considerably less space when removed than its total figure alone would suggest:

docker system df -v | sort -k4 -rh

Sorting by the unique size column specifically, rather than the more commonly noticed total size column, directs cleanup effort toward whichever images actually contribute the most genuinely reclaimable, non-shared disk usage.

Common mistakes

• Summing the size column across multiple images to estimate total disk usage, significantly overstating the actual figure whenever meaningful layer sharing exists between them.
• Assuming an image's full reported size would be reclaimed upon removal, rather than checking its unique size specifically for the accurate, reclaimable amount.
• Prioritizing cleanup based on an image's total reported size rather than its unique, non-shared contribution when genuinely trying to address disk pressure efficiently.
• Not using docker system df -v to access the more precise shared-versus-unique size breakdown when the plain images listing's single combined figure is insufficient for the actual question being asked.
• Comparing size figures across images built from entirely different, unrelated base images and assuming the same layer-sharing dynamic applies, when sharing only occurs between images that genuinely have layers in common.

The images size column reports total, virtual size including shared layers, which makes naive summation across multiple images an unreliable estimate of actual total disk usage, and the more precise shared-versus-unique breakdown available through docker system df -v is the accurate basis for both understanding genuine disk consumption and prioritizing cleanup toward images that would actually free the most reclaimable space upon removal.