Maya stared at the message from her teammate, Sam: "Crashed on startup. Wrong Python version on my laptop."
On Maya’s computer, inside a neat folder called Called_me, sat a single file: app.py. It was a tiny script, just a few lines of Python that printed a greeting and processed a quick calculation. It ran flawlessly on her machine, because her laptop happened to have the right version of Python and the right system libraries already installed. Sam’s didn’t.
Instead of spending an hour debugging Sam’s laptop, Maya decided to use Docker. Rather than sending Sam just her code, she was going to send him an entire, self-contained environment.
Staying right inside her computer’s Called_me folder, she created a new text file named Dockerfile—no extension, just a blueprint. Inside it, she wrote four simple instructions:
FROM python:3.12-slim
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]
She opened her terminal inside Called_me and typed docker build -t called-me:1.0 ..
In a few seconds, Docker read her Dockerfile and forged something completely new: a Docker image. Maya liked to think of an image as a sealed, independent block. It wasn't just her Python script; it was a self-sufficient package containing a full miniature Linux operating system filesystem, the Python 3.12 runtime, all the necessary system libraries, and her code, all bundled together. Whether that block landed on her Windows laptop, Sam’s Mac, or a Linux server in the cloud, it carried its own OS environment inside it and didn't care what was installed on the host machine.
What fascinated Maya most was how Docker actually built that independent block. It didn't mash everything into one giant, messy file. Instead, it built the image as a stack of layers—like stacking sheets of glass on top of each other, one for every line in her Dockerfile.
First, Docker read FROM python:3.12-slim and created Layer 1, laying down the heavy foundation: the base operating system and Python itself. Next, it read WORKDIR /app, which created Layer 2 stacked right on top. Notice the shift in worlds here—this layer didn't touch Maya’s computer at all; it created a brand-new folder named /app inside the image and set it as the active directory. Then came COPY app.py ., which generated Layer 3. For this layer, Docker reached out to the Called_me folder on Maya’s computer, grabbed app.py, and placed a copy of it into the /app folder inside the image. Finally, CMD ["python", "app.py"] created Layer 4—a tiny metadata layer stamped onto the very top, telling the image what to execute when someone eventually runs it.Each line in the Dockerfile directly added a new, distinct layer onto the stack until the full image was complete.
As each layer was created, Docker locked it down and calculated a unique checksum—a long cryptographic fingerprint (a SHA-256 hash) generated from the instruction, the exact contents of the files involved, and the checksum of the layer directly beneath it. Once stamped with that checksum, the layer became permanently read-only.
An hour later, Maya spotted a typo in her code. She opened app.py inside the Called_me folder on her computer, changed a single line, and hit save.
Now, the app.py on her computer was different from the app.py frozen inside the /app folder of her image. To update the image, she ran docker build -t called-me:1.0 . again.
Here was where the read-only rule of Docker images showed its true power—and its strictness. Because an image is immutable, Docker cannot reach into an existing layer, erase one line of app.py, and patch it. Instead, Docker walked down her Dockerfile from the top, checking checksums at every step.
Line one, FROM python:3.12-slim: the checksum matched. Docker reused the cached layer instantly. Line two, WORKDIR /app: the checksum matched. Cached again. Then Docker hit line three: COPY app.py .. It checked the file inside Maya’s Called_me folder, calculated a new checksum, and realized it didn't match the old layer's fingerprint.
The moment that single line changed, the chain broke. Docker couldn't reuse the old COPY layer, and because every layer's checksum depends on the layer beneath it, Docker had to rebuild the COPY app.py . layer and every single layer after it from scratch. It created a brand-new layer holding the updated app.py inside the image's /app folder, stamped it with a new checksum, and rebuilt the final CMD layer on top of it.
In less than a second, the new image was ready. Maya’s computer still held her editable Called_me folder where she could tweak code freely, while the new Docker image sat beside it—a fresh, read-only, independent block, ready to be shipped to Sam so it would run the exact same way on the very first try.
Dangling image
A dangling image is an old, untagged Docker image (<none>:<none>) that has lost its name and is no longer used by any container.
How It Happens in Maya's Story
Earlier, Maya built her first image from the Called_me folder:
docker build -t called-me:1.0 .
Later, she fixed a typo in app.py and rebuilt the image using the exact same tag (called-me:1.0).
Because Docker images are read-only, Docker didn't overwrite her old image. Instead, it built a brand-new image and peeled the called-me:1.0 label off the old one to stick it onto the new one. The old image stayed sitting on Maya's hard drive, stripped of its name—now a dangling image.
When Maya runs docker images, she sees:
REPOSITORY TAG IMAGE ID SIZE
called-me 1.0 9z8y7x6w5v4u 130MB <-- New image (updated app.py)
<none> <none> a1b2c3d4e5f6 130MB <-- Old image (dangling)
Clarification About Disk Space
Looking at that table, it looks like Maya is suddenly using 260 MB (130 MB + 130 MB). She isn't.
-
Shared layers don't take extra space: Both images share Layer 1 (
python:3.12-slim, ~130 MB) and Layer 2 (WORKDIR /app). Docker only stores those shared layers once on disk. -
Only unique layers take extra space: The dangling image only occupies space for the layers that are different from the new image. Since Maya only changed
app.py, the dangling image is only wasting a few kilobytes for her old Layer 3 (COPY app.py .) and Layer 4 (CMD). - When it actually becomes a problem: If Maya changes heavy dependencies (like installing large Python libraries) and rebuilds with the same tag dozens of times, those unique unshared layers do pile up and can quietly eat up gigabytes of disk space.
Cleaning It Up
Whenever Maya wants to clear out those nameless leftovers and reclaim the space from their unique layers, she runs:
docker image prune
Docker deletes the <none>:<none> image, frees the space from its unshared layers, and leaves her active called-me:1.0 image completely untouched.
1. Rebuilding with called-me:2.0
Command:
docker build -t called-me:2.0 .
Output (when Maya runs docker images):
REPOSITORY TAG IMAGE ID SIZE
called-me 2.0 9z8y7x6w5v4u 130MB
called-me 1.0 a1b2c3d4e5f6 130MB
(Note: If Maya did **not* edit app.py before running this, both 1.0 and 2.0 will show the exact same IMAGE ID: a1b2c3d4e5f6.)*
Underlying Meaning:
-
Same project, new version: Docker keeps this image inside the existing
called-merepository and simply marks it as version2.0. -
No dangling image: Because Maya used a new tag (
2.0), Docker does not strip the1.0label off her old image. Both versions stay named and accessible for easy rollback. -
Shared disk space: Even though both rows show
130MB, Docker stores Layer 1 (python:3.12-slim) and Layer 2 (WORKDIR /app) only once on disk. The2.0image only uses a few extra kilobytes for the updatedapp.pylayer.
2. Rebuilding with called-me_hello:1.0
Command:
docker build -t called-me_hello:1.0 .
Output (when Maya runs docker images):
REPOSITORY TAG IMAGE ID SIZE
called-me_hello 1.0 55aa66bb77cc 130MB
called-me 2.0 9z8y7x6w5v4u 130MB
called-me 1.0 a1b2c3d4e5f6 130MB
(Note: If Maya did **not* edit app.py between called-me:2.0 and called-me_hello:1.0, Docker reuses 100% of the cache and both tags will point to the exact same IMAGE ID: 9z8y7x6w5v4u.)*
Underlying Meaning:
-
Brand-new repository name: Changing the name before the colon (
:) tells Docker to register this as a completely separate repository (called-me_hello), treating it like a different app or experimental branch even though it came from the sameCalled_me/folder. -
Still shares base layers: Despite having a different repository name, Docker still recognizes that Layer 1 and Layer 2 have identical SHA-256 checksums, so it reuses them from cache instead of duplicating
130MBon Maya's hard drive. -
Protected from
docker image prune: Becausecalled-me_hello:1.0has a valid name and tag (it is not<none>:<none>),docker image prunewill ignore it. To delete it later, Maya must remove it manually withdocker rmi called-me_hello:1.0.



Top comments (0)