Resources Docker Docker basics

Docker basics · Lesson 3 of 8 · about 25 minutes

Images and registries

Where images come from, what their names mean, why :latest is a trap, how images are built from layers, and how to keep them from filling your disk.

By the end you'll know

  • How to read an image's full name, and where it comes from
  • Why a tag isn't the same as a version, and how to pin one that can't change
  • What layers are, and why they make images fast to download
  • Why an image built on one computer may not run on another
  • How to see what's using your disk, and clean it up safely

Reading an image's name

In Lesson 2 you ran nginx:1.28. That's a short name. The full name has up to four parts:

PartIn ghcr.io/kwamib/civicgrid-api:sha-664d196What it means
Registryghcr.ioWhich library the image lives in. This one is GitHub's.
OwnerkwamibThe person or organization that publishes it
Repositorycivicgrid-apiThe image's name. One repository holds many versions
Tagsha-664d196Which version, after the colon

When you leave parts out, Docker fills them in. The registry defaults to Docker Hub (docker.io), and images with no owner are Docker Official Images, kept under the owner library. So nginx:1.28 really means docker.io/library/nginx:1.28.

A registry is a library of images. Docker Hub is the default, but there are many others: GitHub Container Registry (ghcr.io), and one from each cloud, like Amazon ECR or the DigitalOcean Container Registry. They all work the same way: you pull images from them, and push your own to them (Lesson 8).

Who to trust

Anyone can publish an image to Docker Hub, and an image runs whatever its author put inside it. Before you pull something, check who made it:

  • Docker Official Images (no owner in the name, like nginx or redis) are reviewed and kept up to date by Docker and the projects themselves.
  • Verified publishers, like cloudflare/cloudflared, come straight from the company behind the software.
  • Everything else comes from individuals. Many are great; some are abandoned; a few are malicious. Look at who publishes it, how recently it was updated, and how many people use it.

Tags are labels, not versions

A tag is a label someone sticks on an image, and they can move it to a different image whenever they like. Most projects use tags that look like versions (1.28, 1.28.0) and some that move on purpose:

  • nginx:1.28 points to the newest 1.28.x release, so it moves when a patch comes out.
  • nginx:latest points to whatever the publisher last labeled "latest".

latest is the default. If you write docker run nginx with no tag, Docker uses nginx:latest. That sounds convenient and is the most common way images go wrong: latest today and latest next month can be different versions, with different behavior, and nothing in your files changed. Your app breaks, and you can't tell why.

Think of a recipe card in a shared kitchen. The card says "the house sauce". One day the chef changes the recipe, and your dish tastes different, even though you followed the same card. A tag is that card. A specific version, like 1.28.0, is a dated recipe. And a digest, which you'll meet below, is a photo of the exact sauce you tasted, so nobody can swap it.

The rule of thumb: always name a specific version. Never rely on latest for anything you need to work the same way tomorrow.

If you need a guarantee that the image can never change underneath you, use its digest: a fingerprint of the image's exact contents. A digest looks like nginx@sha256: followed by 64 letters and numbers. If even one byte inside the image changed, the digest would be different, so a digest always means exactly one image.

Try it: pull and look at images

Pull an image without running it, and list what's on your laptop:

BASH
docker pull redis:7.2.7-alpine
docker image ls

docker image ls shows each image's repository, tag, ID, age and size. nginx, busybox and hello-world from Lesson 2 are there too. Notice how small busybox is.

Now find the digest of the Redis image you just pulled:

BASH
docker image inspect redis:7.2.7-alpine --format '{{index .RepoDigests 0}}'

That redis@sha256:... is the fingerprint. Pulling by digest always gives you this exact image, whatever happens to the tag later.

Layers: how images are built

An image isn't one big file. It's a stack of layers, each one a set of changes on top of the layer below: "start from a small Linux system", then "install nginx", then "add its settings". See the layers of the nginx image:

BASH
docker image history nginx:1.28

Each row is a layer, newest at the top, with its size and the step that created it. (Lesson 4 is where you'll make your own.)

Layers matter for two reasons:

  • They're shared. If two images are built on the same base, your laptop stores that base once. When you pull a new version of an image, Docker only downloads the layers that changed. That's why the second pull of a familiar image is often almost instant.
  • They're read-only. When a container starts, Docker adds one thin, writable layer on top for that container alone. Every change the container makes goes there. That's what you saw in Lesson 2: removing a container deletes its writable layer, and the image underneath never changed.
Think of clear plastic sheets on an overhead projector. The bottom sheet has a map; the next adds roads; the next adds labels. Stacked, they make one picture. A container gets its own blank sheet on top to draw on. Draw all you like, then throw that sheet away, and the map underneath is untouched for the next person.
Image layers and container layersThe image nginx:1.28 is a stack of three read-only layers: a small Linux system, then nginx installed, then nginx's settings. Two containers, web and web2, run from it. Each has its own thin writable layer on top, holding only its own changes, which is deleted with the container. Both containers share the same image layers underneath.Container: webits own changesContainer: web2its own changesWritable, one per container,deleted with itLayer 3: nginx's settingsLayer 2: nginx installedLayer 1: a small Linux systemRead-only, shared byevery containernginx:1.28The image never changes. Each container writes only to its own top layer.
An image is a stack of read-only layers. Every container gets its own writable layer on top, so containers never see each other's changes, and removing one leaves the image untouched.

One image, many kinds of computer

A program is built for one kind of processor. Most servers in the cloud use Intel or AMD processors, a family called amd64 (or x86-64). Apple's M-series Macs, and a growing number of cloud servers, use arm64 chips. A program built for one doesn't run on the other.

Popular images handle this by publishing one version per processor under the same tag. Docker quietly picks the one that matches your computer. See every version behind nginx:1.28:

BASH
docker buildx imagetools inspect nginx:1.28

You'll see a list of Platform: lines: linux/amd64, linux/arm64 and more. Check which one your laptop actually downloaded:

BASH
docker image inspect nginx:1.28 --format '{{.Os}}/{{.Architecture}}'

On an M-series Mac that's linux/arm64; on most other laptops, linux/amd64.

This matters most for images you build. An image you build on an M-series Mac is arm64 only, unless you ask for more. Copy it to a typical amd64 server, and it fails to start with exec format error. It catches nearly everyone the first time. Lesson 8 shows the fix: building for the server's processor, or for both at once.

Cleaning up

Images, stopped containers and leftovers from building images all take disk space, and they add up faster than you'd expect. See what's using space:

BASH
docker system df

It lists images, containers, volumes and build cache, with how much of each you could get back (RECLAIMABLE). Then clean up:

BASH
docker system prune

It lists what it will delete and asks first: stopped containers, unused networks, dangling images (old layers with no name left, usually from rebuilding an image) and build cache. Images you've pulled by name are kept. To also delete every image no container is using, add -a. That frees much more space, but anything you need again gets downloaded again.

Break it on purpose

Ask for a version that doesn't exist:

BASH
docker pull nginx:9.99

manifest for nginx:9.99 not found. A manifest is the registry's record of an image, so "manifest unknown" means "there's no image with that tag". When this happens, check the tag against the image's page on its registry. If you did the Kubernetes track, this is the same mistake that left a pod in ImagePullBackOff in the Kubernetes track's Deployments lesson.

Remove an image a container is using:

BASH
docker run -d --name web nginx:1.28
docker rmi nginx:1.28

conflict: unable to remove repository reference "nginx:1.28" (must force) - container ... is using its referenced image. Docker won't delete an image out from under a container, even a stopped one. Remove the container first:

BASH
docker rm -f web
docker rmi nginx:1.28

Now it works. (docker rmi is short for "remove image".)

In my real setup

Every image my production cluster runs is pinned to an exact version. My API is ghcr.io/kwamib/civicgrid-api:sha-664d196: each time I change the code, my CI pipeline (the automated build that runs on every change) builds a new image and tags it with the first seven characters of that change's ID in Git. So every tag points to exactly one version of the code, and rolling back means switching to the previous tag. Redis is redis:7.2.7-alpine, not redis:latest, and the Cloudflare connector is cloudflare/cloudflared:2026.10.0.

The one honest caveat: a tag like sha-664d196 only stays put because I never reuse it. The registry would let me move it. If I needed a hard guarantee, I'd pin by digest.

I learned why pinning matters the hard way. My Redis used to come from a third-party package that wasn't mine. In August 2025, the publisher pulled it from where my setup expected it, and my setup ended up with no Redis address at all. Nothing crashed. With nowhere shared to count, each copy of my API counted each user's requests on its own, and the counts reset on every deploy, so my rate limits were far looser than I thought, until I went looking. Now Redis comes from the official image, pinned to an exact version, under a configuration file I control.

Clean up

BASH
docker rmi redis:7.2.7-alpine

Keep nginx:1.28 and busybox:1.36; the next lessons use them.

Check yourself

  1. What does the short name nginx:1.28 really refer to?

  2. Your app worked last month and broke today, and your files say image: myapp. What's the most likely reason?

  3. Which reference is guaranteed to always mean exactly the same image?

  4. Why is pulling a new version of a familiar image often very fast?

  5. You build an image on an M-series Mac, copy it to a typical cloud server, and it fails with exec format error. Why?

  6. docker rmi nginx:1.28 fails because a container is using the image. What do you do?

Key terms

  • Registry: a library of images, like Docker Hub or GitHub Container Registry.
  • Repository: one image's name, holding all of its versions.
  • Tag: a label after the colon, like 1.28. It can be moved to a different image.
  • latest: the tag Docker uses when you don't name one. It moves, so don't rely on it.
  • Digest: a fingerprint of an image's exact contents, like sha256:.... It always means one image.
  • Layer: one step of changes in an image. Images are stacks of read-only layers.
  • Platform: the operating system and processor an image is built for, like linux/amd64 or linux/arm64.
  • docker system prune: deletes stopped containers, unused networks, dangling images and build cache.

Go deeper

From www.kwamib.dev/resources/docker/images-and-registries