Images are the deliverable of everything you do with Docker. This lesson covers the day-to-day image commands, how to publish to a registry, how to keep disks from filling up, and how to pick a base image that is small and safe.
Pull and list images
docker pull downloads an image without running it. Pin a version tag so you know what you get:
$ docker pull postgres:17-alpine
17-alpine: Pulling from library/postgres
Digest: sha256:7c688148e5e156d0e86df7ba8ae5a05a2386aaec1e2ad8e6d11bdf10504b1fb7
Status: Downloaded newer image for postgres:17-alpine
docker.io/library/postgres:17-alpine
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
postgres 17-alpine 2f1c7a9b4e3d 9 days ago 278MB
nginx 1.27 a6b2c9e1f0d4 3 weeks ago 192MB
hello-node 1.0 c4e8f1a2b7d9 2 hours ago 160MB
Inspect what is inside
docker image inspect prints the full metadata as JSON. Use --format to pick fields, such as the default command, environment and exposed ports:
$ docker image inspect --format '{{.Config.Cmd}} {{.Config.ExposedPorts}}' nginx:1.27
[nginx -g daemon off;] map[80/tcp:{}]
$ docker image inspect --format '{{.Os}}/{{.Architecture}}' nginx:1.27
linux/amd64
To look around inside an image without starting its normal process, override the command with a shell:
$ docker run --rm -it nginx:1.27 sh -c 'ls /usr/share/nginx/html'
50x.html index.html
Tag and push to a registry
A tag is a pointer, and one image can have many. To publish, tag the image with the registry and repository name, log in, then push:
$ docker tag hello-node:1.0 ghcr.io/jeff/hello-node:1.0
$ echo "$GHCR_TOKEN" | docker login ghcr.io -u jeff --password-stdin
Login Succeeded
$ docker push ghcr.io/jeff/hello-node:1.0
The push refers to repository [ghcr.io/jeff/hello-node]
5f70bf18a086: Pushed
1.0: digest: sha256:9b2e64f0c1d7a3e85b4f6c2d1a0e9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f size: 1365
Tip: --password-stdin keeps the token out of your shell history and process list. In CI, use the registry’s short-lived tokens instead of personal passwords.
Most teams push two tags per build: an immutable one (the version or git SHA) for deploys, and a moving one like main for convenience.
Choose a base image
The FROM line decides most of your image’s size and its security surface:
| Base image | Size (approx.) | Good for | Watch out for |
|---|---|---|---|
ubuntu:24.04, debian:12 | 75–120 MB | Familiar tools, easy debugging | Larger, more packages to patch |
*-slim variants | 30–80 MB | Most apps: Debian with the extras removed | Missing tools like curl until you add them |
alpine | 5–10 MB | Tiny images, fast pulls | Uses musl instead of glibc; some binaries misbehave |
gcr.io/distroless/* | 2–30 MB | Production runtimes with no shell | No shell to debug with |
scratch | 0 MB | Static binaries (Go, Rust) | Nothing at all: add certificates yourself |
Start with the official -slim image for your language, and move to distroless once your build is stable.
Build for amd64 and arm64
Laptops with Apple silicon and ARM servers (such as AWS Graviton or Oracle Ampere) use arm64, while most other machines use amd64. Buildx builds both and pushes one multi-platform tag:
$ docker buildx create --use --name multi
multi
$ docker buildx build --platform linux/amd64,linux/arm64 \
-t ghcr.io/jeff/hello-node:1.1 --push .
=> [linux/amd64 1/3] FROM docker.io/library/node:22-alpine
=> [linux/arm64 1/3] FROM docker.io/library/node:22-alpine
=> pushing manifest for ghcr.io/jeff/hello-node:1.1
Every machine pulling hello-node:1.1 now gets the variant for its own CPU.
Clean up disk space
Images pile up quickly on build machines. See what Docker uses, then prune:
$ docker system df
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 23 4 6.42GB 5.1GB (79%)
Containers 5 2 12.3MB 8.1MB (65%)
Local Volumes 3 2 1.2GB 240MB (20%)
Build Cache 41 0 2.3GB 2.3GB
$ docker image prune
Total reclaimed space: 1.08GB
$ docker image prune -a --filter "until=168h"
docker image prune only removes dangling images (no tag). With -a it removes every image not used by a container; the filter keeps anything newer than a week.
Exercise
An image built on an Apple Silicon Mac fails on the production amd64 server with “exec format error”. What fixes it?
Show answer
Answer: C. The Mac produced arm64 binaries that an amd64 CPU cannot execute. Buildx can build one multi-platform image, and each server pulls the variant that matches its CPU.
Key takeaways
- Pin image tags, and use digests when you need exact reproducibility.
docker image inspect --formatanswers “what does this image run?” without starting it.- Tag with the registry name, log in with
--password-stdin, thendocker push. - Pick
-slimor distroless bases, build multi-platform with Buildx, and prune regularly.
FAQ
Why does my image work on my Mac but fail on the server with “exec format error”?
It was built for arm64 (Apple silicon) and the server is amd64, or the other way around. Build with --platform linux/amd64, or build a multi-platform image with Buildx.
How do I scan an image for vulnerabilities?
Run docker scout cves <image>, or use an open source scanner such as Trivy (trivy image <image>). Add the scan to CI so vulnerable images never reach production.
Can I delete an image that a container is using?
Not while a container (even a stopped one) references it. Remove the container first, or use docker rmi -f, which only removes the tag and leaves the data in use.