You have spent three lessons building. Every docker build from the previous ones has left layers on your disk, and by now your machine has accumulated auroralibros/aurora-api in several versions, the node, postgres, redis, nginx and alpine base images, the lab images from the exercises and a BuildKit cache you have never looked at. This lesson is about administering that store: knowing what you have, why it takes up what it takes up, how to audit what an image is made of, how to delete without wiping out what you need, where those mysterious <none>:<none> images that show up build after build come from, and how to take an image to another machine when there is no registry involved. It is the least flashy lesson of the module and the one that will save you the most grief: a misunderstood docker system prune -a --volumes destroys in ten seconds data that took weeks to produce.

1. Listing images: docker image ls and its options
2. Inspecting: docker image inspect and --format
3. Auditing how it was made: docker image history
4. Deleting images: docker image rm
5. Dangling images: the <none>:<none> ones
6. Cleaning up with the prune family
7. Diagnosing disk space: docker system df
8. Moving images without a registry: save/load and export/import
9. A recommended maintenance routine

The starting point, using the docker <object> <action> grammar from lesson 01-04:

docker images is the short alias and does exactly the same thing.

A fundamental warning about the SIZE column, which you already suspected in lesson 01-05: the sizes do not add up. The three versions of aurora-api each say 167 MB, but they do not take up 501 MB on disk. They share the node:22-alpine base and a good part of their layers; the real space is what docker system df will tell you in section 7.

The digest comes out as <none> because these images were built locally and have never been published: the manifest digest is assigned by the registry when it receives the push. As soon as you publish them in lesson 02-06, that column will fill in.

Only 1.1.0 shows up, because it is the only one carrying the OCI labels. Here you can see the practical payoff of the previous lesson's work: the metadata was not decoration, it is a queryable index.

Bringing back --format from lesson 01-04:

Available fields: .ID, .Repository, .Tag, .Digest, .CreatedSince, .CreatedAt, .Size.

Without the word table, the output is plain text, perfect for scripts:

And in JSON, to process with jq:

docker image inspect dumps all of an image's metadata as JSON. With no filter it is hundreds of lines:

The trick is extracting only what you need. The --format syntax is the same as in lesson 01-04, and these are the fields you will use most:

This is the command you use to audit that there is no secret inside an image before publishing it. Make it a reflex.

If this said linux/amd64 and you were on a Mac with Apple Silicon, the image would run under emulation, which is much slower. It is the first thing to check when a container is inexplicably slow.

One command, and you know exactly which commit is inside that image.

You can inspect several at once and compare:

There is the complete genealogy: Alpine contributes 1 layer, Node adds 3 more, and your Dockerfile the remaining 3 (the two COPYs and the RUN).

docker image history reconstructs an image's build history layer by layer. It is the auditing tool par excellence and you already used it in lesson 02-01 to evaluate other people's images.

How to read it:

• You read it from the bottom up. The last line is the first layer (Alpine's base filesystem); the first line is the most recent instruction.
• <missing> is not an error. Only the top layer has an ID of its own; the intermediate ones of an image built with BuildKit do not expose theirs. That is normal.
• The SIZE column is the one that matters. There you can see that the RUN npm ci contributes 24.7 MB and the two COPYs barely 52 kB and 44 kB between them. All the metadata — ENV, EXPOSE, USER, LABEL, HEALTHCHECK, ENTRYPOINT, CMD — weighs 0 B, exactly as announced in the previous lesson.
• The history includes the base image's. The "6 days" lines belong to node:22-alpine: you can see how its maintainers built it.

It is the command's most profitable use:

When an image weighs 900 MB and you do not know why, this command gives you the answer in a second. The usual suspects: uncleaned package manager caches, build tools that stayed inside and temporary files deleted in a different layer (with the null effect you demonstrated in lesson 02-03).

By default the CREATED BY column is cut off. To audit properly, you need the whole text:

This is the command with which you spot a suspicious curl … | sh in somebody else's image, the installation of a tool you were not expecting or, in your own image before publishing it, a --build-arg with a password like the one in lesson 02-04.

An honest limitation: history shows the instructions, not the content. A file copied with COPY does not show up here. For that, start the image and look (docker run --rm image ls -la /app) or use third-party tools such as dive (lesson 07-04).

docker rmi is the short alias. Look at the output: Untagged and Deleted are two different things, and understanding the difference is the key to this whole section.

When two tags point at the same image (the same IMAGE ID), deleting one does not delete the image:

The same IMAGE ID: it is one image with two names, not two 167 MB images. Now delete one:

Only Untagged, with no Deleted at all. The name has been removed; the data is still there because 1.1.0 still references it. Deleted only appears when the last reference disappears. This is why you sometimes delete an image and do not get a single byte of disk back.

Deleting by ID when several tags point at that image fails:

Docker refuses because it does not know which name you want to remove. Either you delete each tag by its name, or you use -f to remove them all at once.

The most frequent of all:

The container is stopped, not running, and it still blocks the deletion. It is entirely logical: as you learned in lesson 01-05, a stopped container keeps its writable layer, which is stacked on top of the image's layers. Deleting the image would leave that layer floating on nothing, and the container would not be able to start again.

The three possible ways out:

When is -f acceptable? Less often than it is used:

The danger of -f on a running container: the image is "deleted" from the listing but its layers keep taking up disk as long as the container lives, and the container will not be able to restart once it is stopped. You end up with a service that works until its first restart and is then unrecoverable, with no way to rebuild it other than the registry. It is a classic production incident.

The $(docker image ls -q …) pattern combines -q (IDs only) with the shell's command substitution. Before running a bulk deletion, run just the inner part first to see what you are about to destroy:

Sooner or later you will see this:

Those <none>:<none> entries are dangling images: real, complete and perfectly functional images that have lost their name.

The main cause, by far, is rebuilding with the same tag:

On the second build a new image is born (different content, different ID) and the 1.1.0 tag moves to it. Image A is not deleted: it is left without a name. It is exactly the model from lesson 02-01 — tags are movable pointers to immutable digests — seen from the local side.

Check it:

The other two sources:

• Builds without -t. docker build . produces a nameless image from the very first second. That is the reason for the tip in lesson 02-02: always tag.
• Failed builds that left intermediate layers behind.

Because they pile up silently. A developer who rebuilds twenty times a day with the same tag generates twenty dangling images daily. Most of them share layers and do not take up 167 MB each, but the layers of their own (the COPY . . and sometimes the RUN npm ci) are exclusive. In a few weeks that is several gigabytes, and the no space left on device message arrives at the worst possible moment.

They are not absolute garbage: if you know their ID, you can run them and even retag them.

That saves the day when you accidentally delete the tag of an image you had not published yet. But as a matter of routine, they get cleaned up.

Four commands, with four very different blast radii. This table is the one to memorize:

This is the one you can run with confidence: it only takes away nameless images. With -f it skips the confirmation (useful in scripts) and with --filter "until=168h" it limits the deletion to those older than a week:

Read the warning carefully: it deletes every image that has no associated container, not just the dangling ones. If you have no containers created — which is normal after cleaning up — this takes away node:22-alpine, postgres:16-alpine, redis:7-alpine, your local aurora-api images and everything else. It is not catastrophic (things can be rebuilt and re-downloaded), but it means gigabytes of downloads and, if you are offline or close to the pull limit from lesson 02-01, a bad time.

BuildKit's cache is invisible in docker image ls and is usually the bulkiest thing on the machine:

Almost three gigabytes that did not appear in any image listing. Variants:

The trade-off: the next build of each project will run cold. Remember from lesson 02-02 that this is precisely where the cache does not help.

The warning lists exactly what it is going to delete. Always read it: it is the difference between cleaning up and losing work. What it takes away by surprise is usually a stopped container that held data in its writable layer, or a network you created by hand for some testing.

This is the line that ruins your day: all volumes not used by at least one container.

Translated to Aurora Libros: when in module 3 you have a volume with the PostgreSQL catalog and you have stopped and deleted the aurora-db container in order to recreate it, that volume is temporarily left with no associated container. A docker system prune -a --volumes at that moment deletes the entire database. No recycle bin, no undo, no recovery.

Rules of use:

• Never on a server. Never.
• In development, only when you are certain there is no volume you care about.
• Before running it, look at which volumes exist:

• If all you want is space, the safe ladder is: docker image prune → docker builder prune → docker system prune. You rarely need to reach the last rung.

Before deleting anything, measure.

How to read it:

Two immediate conclusions from this example:

1. Nine images take up 842 MB, not the sum of their SIZE columns in docker image ls (which would come to more than 1.2 GB). The difference is the shared layers from lesson 01-05, counted only once.
2. The build cache is 2.85 GB, 100% reclaimable, and it is by far the biggest thing there. It is the first thing to clean up, and it did not appear in any image listing.

The SHARED SIZE and UNIQUE SIZE columns are what clear everything up:

• node:22-alpine: 142 MB in size, 142 MB shared, 0 B unique. Deleting it would free nothing, because all its layers are used by your aurora-api images.
• aurora-api:1.0.0: 167 MB, of which only 24.7 MB are exclusive. That is what you would gain by deleting it.
• postgres:16-alpine: 278 MB with 270 MB unique. This one is a good candidate if you are not going to use it.

And look at the last volume line: f3a9c2e1b8d7… with 0 links is an orphaned anonymous volume, exactly what lesson 02-04 anticipated when it advised against VOLUME in a Dockerfile. It takes up 61.7 MB and nobody knows what is in it.

Sometimes you have to take an image to another machine with no registry in between: a client with an air-gapped network, an environment with no internet access, a demo on a laptop with no connection. Docker offers two pairs of commands that get confused constantly and that are not interchangeable.

The rule: to move an image, always save/load. export/import is for something else.

From 168 MB to 62 MB: 63% less, and that is what travels on the USB stick or over SCP. You can also do it in a single step with a pipe:

The same IMAGE ID, the same ENTRYPOINT, the same USER. The image has arrived intact, with all the metadata you defined in lesson 02-04.

Saving several images into a single file, useful for taking the entire Aurora Libros stack with you:

A single file with everything needed to bring the platform up on a machine with no internet.

It works on containers, not images, and it flattens the result:

A single layer and no history at all. The whole genealogy has vanished. And the serious part:

The ENTRYPOINT, the CMD, the ENV, the USER and the EXPOSE have all been lost. The imported image is a filesystem with no instructions. You would have to supply them by hand at runtime:

So what is it good for? For two legitimate things:

1. Flattening an image with too many layers or with a secret buried in an intermediate layer that you want to remove for real. When you flatten, that layer disappears. (The modern and better way to achieve this is multi-stage builds, lesson 05-04.)
2. Extracting the filesystem of a container to analyze it forensically or to build a base image from an existing system.

You can restore the metadata at import time, with -c:

It works, but you have had to rebuild by hand what save preserved on its own. It is clear which is the right tool for moving images.

Cleanup:

With all of the above, this is a reasonable routine for a development machine.

Weekly (safe, can be automated):

It deletes dangling images and build cache older than a week, and shows how the space looks afterwards. It touches nothing that has a name, no containers and no volumes.

Monthly (manual review):

Nothing gets automated here: you look and you decide. Orphaned volumes have to be inspected before deleting them, because they may contain data.

Before an important build:

A clean cache and an up-to-date base, as explained in lesson 02-02.

When you are out of space, the safe ladder:

In five steps ordered from least to most risk you almost always recover several gigabytes without ever reaching docker system prune -a --volumes.

A maintenance script with a report:

Notice the last section: it lists the orphaned volumes but does not delete them. That is the line that separates a maintenance script from a data-destruction script.

• Adding up the SIZE column of docker image ls. It is not disk space: shared layers are counted in every row. The real figure is in docker system df, and the breakdown in docker system df -v.
• Deleting a tag and expecting to recover space. If the output only says Untagged and not Deleted, you have freed nothing: the image has another reference.
• docker image rm -f on a running container. The image "disappears" but its layers stay on disk and the container will never be able to restart. Stop the container first.
• docker system prune -a --volumes without reading the warning. It deletes volumes with no associated container, and a database volume between container recreations is in exactly that state. Never on a server.
• Ignoring the BuildKit cache. It does not show up in docker image ls and it is usually the bulkiest thing on the machine. docker system df gives it away.
• Confusing save/load with export/import. export loses ENTRYPOINT, CMD, ENV, USER and the history, and the imported image gives no command specified. To move images, always save/load.
• Forgetting to compress the .tar. A gzip -9 usually cuts between 50% and 65%.
• Tip: audit the variables before publishing. docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' should be a reflex before any docker push.
• Tip: use docker image history … | sort -rh to hunt down fat layers. It is the "why is this image so big" diagnosis in a single command.
• Tip: always tag with -t. Every untagged build is a dangling image from the very first second.
• Tip: before a bulk deletion, run just the inner part of the $( … ) to see what you are about to destroy.

1. Run docker system df and note the total and the reclaimable percentage of each category.
2. With docker system df -v, identify the image with the largest UNIQUE SIZE and the one with a UNIQUE SIZE of 0 B. Explain what each case means and how much deleting each one would free.
3. Use docker image history to locate the heaviest layer of auroralibros/aurora-api:1.1.0 and of postgres:16-alpine.
4. Check whether you have orphaned volumes and work out, without deleting them, which image they came from.

1. Build auroralibros/aurora-api:experiment from your Dockerfile and note the IMAGE ID.
2. Create a second tag, auroralibros/aurora-api:copy, pointing at the same image. Check that the ID matches and that docker system df has not grown.
3. Delete the copy tag. Does it say Untagged, Deleted or both? Why?
4. Modify server.js, rebuild with the same experiment tag and check that a <none>:<none> image appears. Explain where it came from.
5. Recover that dangling image by retagging it as auroralibros/aurora-api:rescued and verify that it works.
6. Clean up everything created in the exercise.

Simulate a deployment in an air-gapped environment:

1. Export auroralibros/aurora-api:1.1.0, postgres:16-alpine and redis:7-alpine into a single file.
2. Compress it and note the size before and after.
3. Delete the three images from your machine (simulating a blank target machine).
4. Load them from the file and verify that aurora-api keeps its ENTRYPOINT, USER, ENV and HEALTHCHECK.
5. Repeat the cycle with export/import on an aurora-api container and compare: tar size, number of layers in the history and behavior when running docker run with no arguments. Conclude which pair you would use and why.

Solution to exercise 1

1. Approximate total: 3.95 GB, of which 3.65 GB are reclaimable. The build cache is 72% of everything and it is 100% reclaimable: it is the priority target.

2.

• Largest UNIQUE SIZE: postgres:16-alpine, with 270 MB unique out of its 278 MB. The only thing it shares with the rest is Alpine's base layer (8.17 MB). Deleting it would free 270 real MB.
• UNIQUE SIZE of 0 B: node:22-alpine. Its 142 MB are entirely shared with your aurora-api images, which were built on top of it. Deleting it would not free a single byte as long as some derived image exists; it would only disappear from the listing. It is the practical demonstration of the shared layers from lesson 01-05.

3.

In aurora-api, the npm ci with 24.7 MB is the biggest contributor of its own: those are the production dependencies. In postgres, the 248 MB from compiling PostgreSQL explain its size on their own.

4.

The content gives away its origin: it is an anonymous volume created by the PostgreSQL image, which declares VOLUME /var/lib/postgresql/data in its Dockerfile. It is exactly the scenario lesson 02-04 gave as a reason not to use VOLUME. Do not delete it without checking the content: it could be a database with real work inside.

Solution to exercise 2

The same ID and the same total space. docker image tag only creates a reference; it does not copy a single byte. It is the local demonstration of what you will see in the registry in lesson 02-06.

Only Untagged. There is no Deleted because the experiment tag still points at that image: the data is still referenced and the deletion is limited to removing the name.

The ID 4e9c7d2a8f31 is the same as in step 1: the original image has not been deleted, it has lost its name. The new build produced a different image and the experiment tag moved to it. Tags are pointers, not owners.

Recovered and functional, and it no longer shows up as dangling because it has a name again. Notice that --version worked thanks to the ENTRYPOINT ["node"] from lesson 02-04.

Solution to exercise 3

From 481 MB to 173 MB: 64% less. Compressing is always worth it, especially if the file travels over SCP or on a USB stick.

Absolutely everything intact: entrypoint, cmd, user, variables, healthcheck and even the OCI labels with the commit hash.

The final comparison table:

Conclusion: to move images, save/load, no argument. The small size saving from export does not make up for losing all the runtime configuration, the healthcheck and the traceability that took a whole lesson to build. export/import is a tool for flattening filesystems, not for moving images.

Cleanup:

You now know how to administer your image store. You list and filter with docker image ls, its --filters (including filtering by the OCI labels you added in 02-04) and its Go templates. You extract any specific piece of metadata with docker image inspect --format, and you have a new reflex worth keeping: auditing the environment variables before publishing any image. With docker image history you reconstruct how an image was made, layer by layer, and you find in a single command the one that ate the megabytes — in aurora-api, the npm ci with 24.7 MB; in postgres, the 248 MB of its compilation.

You know how to delete while understanding what is happening: Untagged removes a name and Deleted destroys data, and it only appears when the last reference falls. You know why a stopped container blocks the deletion of its image (it keeps its writable layer stacked on top) and when -f is acceptable and when it is an elegant way of breaking a service at its next restart. You understand where the <none>:<none> images come from: rebuilding with the same tag moves the pointer and orphans the previous image, which stays on disk and can even be rescued by retagging it.

You have mastered the cleanup ladder, from least to most risk — image prune, builder prune, system prune — with a warning burned in about the last rung: docker system prune -a --volumes deletes volumes with no associated container, and a database volume between container recreations is in exactly that state. You measure before touching anything with docker system df and its -v version, which reveals what no image listing shows: the BuildKit cache taking up gigabytes, the shared layers counted only once and the SHARED/UNIQUE columns that tell you how much you would really free by deleting each image. And you know how to take an image to an air-gapped machine with docker save/load, preserving entrypoint, user, healthcheck and OCI labels, as opposed to export/import, which flattens the filesystem and loses everything.

Your image is built, it is professional and you know how to maintain it. It is missing the one thing that justified the whole module: leaving your machine. In the final lesson, Tagging and Publishing Images, you will close the cycle. You will see that docker image tag copies nothing but creates references, you will decide a serious tagging strategy — semantic versioning with moving and fixed tags, by commit SHA, by branch, by environment — and you will publish auroralibros/aurora-api to Docker Hub and to GitHub Container Registry, reading the push output, verifying the result with docker manifest inspect and understanding why production deploys by digest and never by latest.