Introduction

Docker image size reporting can be confusing because layered storage means there is more than one useful definition of "size." The basic distinction is that plain size usually refers to bytes directly associated with the image object or layer set, while virtual size refers to the cumulative apparent size including parent layers. Shared layers make the numbers look larger than the actual additional disk cost of one image.

Docker Images Are Layered

A Docker image is built from layers stacked on top of each other. If two images share a base layer, Docker stores that layer once on disk.

1FROM python:3.12-slim
2WORKDIR /app
3COPY requirements.txt .
4RUN pip install -r requirements.txt
5COPY . .
6CMD ["python", "main.py"]

Each instruction can create or reference a layer. When another image uses the same python:3.12-slim base, Docker can reuse the shared layers instead of duplicating them.

That sharing is why the cumulative size of an image chain and the extra disk space consumed by one image are not always the same concept.

What Virtual Size Means

Historically, Docker used "virtual size" to describe the cumulative size of an image plus its parent layers. In other words, it answers a question like:

"If I add up all layers that make this image usable, what total size do they represent?"

That is useful for understanding the logical footprint of the full image stack, but it does not mean all of those bytes are unique to that image on disk.

If a 200 MB base layer is shared by ten images, the virtual size of each image may include that base, even though the host stores it only once.

What Plain Size Usually Means

The plain size value is generally closer to the image's own stored data contribution, or at least the non-cumulative size being reported for that object. Depending on the Docker command or API field, the exact definition can vary, but the main practical contrast remains the same:

• size is the direct size being reported for that image object or writable layer contribution
• virtual size is the larger cumulative view including inherited layers

This is why virtual size is often equal to or larger than size.

Why Disk Usage Can Still Differ

Even virtual size is not the same as real additional disk usage on a host with many shared layers. Suppose you have:

• a 150 MB base image
• image A adds 20 MB
• image B adds 30 MB

The virtual sizes may look like 170 MB and 180 MB, but the host may store only:

• 150 MB once for the base
• 20 MB for A's unique layer
• 30 MB for B's unique layer

So the extra disk usage of adding image B after image A is closer to 30 MB than to 180 MB.

That is the most important operational insight: Docker's reported sizes are about layer composition, not just "how many brand-new bytes this image costs right now."

A Practical Way To Think About It

For image optimization, ask three separate questions:

• what is the full cumulative image footprint
• how much unique data does this image add
• how much actual disk is being consumed after layer sharing

The Docker reporting you see may answer only one or two of those.

This is also why image-cleanup decisions should consider shared layers. Removing one image may free little disk space if most of its layers are still referenced elsewhere.

Common Pitfalls

A common mistake is treating virtual size as actual extra disk usage. Shared layers mean that is often wrong.

Another mistake is assuming every Docker command reports size fields with exactly the same meaning. Historical commands, APIs, and container views have used related but slightly different size terms.

Developers also sometimes optimize a child image aggressively while ignoring a very large shared base image. Total pull cost and local storage footprint are often dominated by the base.

Finally, remember that container writable-layer size is a separate concept again. Image size and container runtime growth are related, but they are not the same metric.

Summary

• Docker images are built from reusable layers.
• Virtual size is the cumulative apparent size including parent layers.
• Plain size is the more direct size being reported for the image object or non-cumulative contribution.
• Shared layers mean reported size is not the same as additional disk cost.
• Removing one image does not necessarily free its full virtual size.
• Think separately about cumulative footprint, unique layers, and actual host disk usage.