Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 111 Β· Images

Pulling and Managing Images

Learn to download, list, tag, filter and delete Docker images: docker pull, images, rmi, dangling images, label-filtered prune and docker search, with real output.

Images arrive on your machine through docker pull, sit in the local image store, and stay there until you delete them. Learning to manage that store is a small skill with a big payoff: you will know exactly what a pull downloads, why a second pull is instant, why docker images seems to show the same image twice, what a "dangling" image is, and how to reclaim disk space without removing something you need.

This lesson covers the day-to-day commands: pull, images, tag, rmi, prune and search. If the words layer, tag and digest are not yet clear, read Understanding Images first.

docker pull

docker pull NAME[:TAG|@DIGEST] downloads an image from a registry (Docker Hub unless you name another). You rarely have to run it by hand, because docker run pulls automatically when the image is missing. Explicit pulls are useful to prepare machines, to refresh a moving tag, or to check a name.

CONSOLE
$ docker pull busybox:1.36
1.36: Pulling from library/busybox
034d6572bf28: Pulling fs layer
5108bc06b83a: Download complete
034d6572bf28: Download complete
034d6572bf28: Pull complete
Digest: sha256:73aaf090f3d85aa34ee199857f03fa3a95c8ede2ffd4cc2cdb5b94e566b11662
Status: Downloaded newer image for busybox:1.36
docker.io/library/busybox:1.36

(On a terminal you see progress bars that update in place; when output is piped or logged, as here, Docker prints one line per event.) Read it line by line:

  1. Pulling from library/busybox is the repository: the unqualified name busybox means docker.io/library/busybox.
  2. Each hex string is a layer (shortened blob ID). Layers are fetched in parallel: Pulling fs layer, then Download complete, then Pull complete once the layer is unpacked and stored. Layers you already have are skipped, shown as Already exists (you will see that when two images share a base).
  3. Digest: is the digest of the manifest (index) you received. Save it if you want to pin the image.
  4. Status: summarizes the outcome. Downloaded newer image means something new was fetched.

Pulling again: the update check

Run the same pull a second time:

CONSOLE
$ docker pull busybox:1.36
1.36: Pulling from library/busybox
Digest: sha256:73aaf090f3d85aa34ee199857f03fa3a95c8ede2ffd4cc2cdb5b94e566b11662
Status: Image is up to date for busybox:1.36
docker.io/library/busybox:1.36

Docker asks the registry which digest the tag points to now. If it equals the local one, nothing is downloaded. If the publisher moved the tag to a new image (a security patch, say), only the changed layers are fetched and the tag on your machine moves to the new image; the previous image stays as an untagged "dangling" image until you remove it.

This also explains a common surprise: docker run nginx does not update nginx. If an image with that name exists locally, run uses it and never contacts the registry. To get the newest version of a tag, docker pull nginx first (or use docker run --pull always).

Choosing a version

CONSOLE
$ docker pull -q busybox:1.36
docker.io/library/busybox:1.36

-q (quiet) prints only the resulting reference, which is convenient in scripts. A few forms you will use:

You write You get
docker pull busybox busybox:latest
docker pull busybox:1.36 The image the tag 1.36 points to
docker pull busybox@sha256:73aaf0... Exactly that manifest, whatever the tags say
docker pull ghcr.io/owner/app:v2 An image from another registry (read-only example)
docker pull --platform linux/arm64 busybox The variant for another CPU architecture

--platform matters when your machine and your target differ, for example building on an Apple Silicon laptop for an x86 server; see Multi-Platform Images.

Errors you will meet

CONSOLE
$ docker pull tcd-nonexistent-xyz:1
Error response from daemon: pull access denied for tcd-nonexistent-xyz, repository does not exist or may require 'docker login'
$ docker pull busybox:no-such-tag
Error response from daemon: failed to resolve reference "docker.io/library/busybox:no-such-tag": docker.io/library/busybox:no-such-tag: not found

The first message has two possible causes that Docker deliberately does not distinguish: the repository really does not exist, or it is private and you are not logged in (so that nobody can probe which private repositories exist). Check the spelling, then check docker login. The second means the repository exists but the tag does not: look at the repository's tag list.

Listing images

CONSOLE
$ docker images busybox
IMAGE            ID             DISK USAGE   CONTENT SIZE   EXTRA
busybox:1.36     73aaf090f3d8       12.9MB         4.11MB
busybox:1.37     bdf57e528e45       6.77MB         2.22MB
busybox:latest   fd7dc98638c8       6.81MB         2.23MB

docker images is short for docker image ls. Giving a repository name filters the list. In Docker 29 each row is one tag, with these columns:

  • ID is the first 12 characters of the image ID.
  • DISK USAGE is the size of the image unpacked in the local store.
  • CONTENT SIZE is the compressed size of the content you downloaded (or would upload). The same image is much smaller in the registry than on disk.
  • EXTRA shows a U when at least one container (running or stopped) uses the image. That helps you spot what rmi will refuse to delete.

Older Docker versions printed REPOSITORY, TAG, IMAGE ID, CREATED and a single SIZE. The --digests flag still gives that classic table with digests:

CONSOLE
$ docker image ls --digests busybox:1.36
REPOSITORY   TAG       DIGEST                                                                    IMAGE ID       CREATED   SIZE
busybox      1.36      sha256:73aaf090f3d85aa34ee199857f03fa3a95c8ede2ffd4cc2cdb5b94e566b11662   73aaf090f3d8   3 years   ...

Filtering and formatting

As with docker ps, you can filter with --filter and shape the output with --format:

CONSOLE
$ docker image ls --format '{{.Repository}}:{{.Tag}}' --filter reference='busybox*'
busybox:latest
busybox:1.37
busybox:1.36
$ docker images -q busybox
fd7dc98638c8
bdf57e528e45
73aaf090f3d8
$ docker images --filter reference='tcd-app*' --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Size}}'
REPOSITORY   TAG       IMAGE ID       SIZE
tcd-app      2         2394aac19c8c   6.78MB

Useful filters are reference= (name patterns with *), dangling=true, label=key[=value], before= and since= (images created before or after another image). -q prints only IDs, ready to feed into other commands. See Listing and Inspecting for how --format templates work.

One image, several names: docker tag

A tag is a name pointing at an image. docker tag SOURCE TARGET adds a name without copying anything:

CONSOLE
$ docker tag busybox:1.36 myteam-busybox:a
$ docker tag busybox:1.36 myteam-busybox:b
$ docker images myteam-busybox
IMAGE               ID             DISK USAGE   CONTENT SIZE   EXTRA
myteam-busybox:a    73aaf090f3d8       12.9MB         4.11MB
myteam-busybox:b    73aaf090f3d8       12.9MB         4.11MB

Both rows have the same ID and, as the previous lesson explained, the disk usage is not doubled. Tagging is how you prepare an image to be pushed to your own repository; that is the topic of Tags and Registries.

Removing images: docker rmi

docker rmi NAME... (docker image rm) removes names. When the last name of an image is gone and no container needs it, the layers are deleted too.

CONSOLE
$ docker rmi myteam-busybox:a
Untagged: myteam-busybox:a
$ docker images myteam-busybox --format '{{.Repository}}:{{.Tag}}'
myteam-busybox:b

Only the name :a went away; the image is still there under :b (and as busybox:1.36). Removing the last name shows the second line, Deleted:, with the image's ID:

CONSOLE
$ docker rmi busybox:1.35
Untagged: busybox:1.35
Deleted: sha256:98ad9d1a2be345201bb0709b0d38655eb1b370145c7d94ca1fe9c421f76e245a

An image in use

Docker refuses to remove an image that a container (even a stopped one) was created from:

CONSOLE
$ docker run -d --name tcd-use tcd-app:1 sleep 600
$ docker rmi tcd-app:1
Error response from daemon: conflict: unable to delete tcd-app:1 (must be forced) - container 1c6f8bdbc70f is using its referenced image d831922f29c7

The message tells you which container to remove first. With -f Docker removes the name anyway:

CONSOLE
$ docker rmi -f tcd-app:1
Untagged: tcd-app:1
$ docker ps -a --filter name=tcd-use --format '{{.Image}}'
d831922f29c7

The container keeps running (it holds on to the layers it uses) and now shows a bare image ID instead of a name. That usually leaves you with a confusing container that you can no longer recreate by name, so prefer docker rm the container first, then docker rmi.

Do not "fix" disk space problems with docker rmi -f $(docker images -q). It removes every name on the machine, including images that running containers and your teammates' projects depend on. Remove what you can name, or prune with a filter (below).

Dangling images

An image that has lost all its tags is shown as <none> or <untagged>, and Docker calls it dangling. It appears in three situations: you forced-removed the last tag of an image that a container uses (as above), you rebuilt an image under the same tag so that the old build lost the name, or a pull moved a tag to a newer image.

CONSOLE
$ docker images --filter dangling=true
IMAGE        ID             DISK USAGE   CONTENT SIZE   EXTRA
<untagged>   d831922f29c7       6.78MB         2.21MB

Dangling images are not harmful, but they pile up on build machines and take disk space. docker image prune deletes them. It asks for confirmation; add -f to skip it. Be careful: on a shared machine, plain prune removes dangling images that belong to everyone. A filter keeps it precise. Our test image was built with LABEL tcd=b2, so we can restrict the cleanup to it:

CONSOLE
$ docker image prune --filter label=tcd=b2 -f
Deleted Images:
untagged: sha256:d831922f29c7b7af9c497c83978ec7759727e0aad0a63ad3b08563eb76924ef4
deleted: sha256:d831922f29c7b7af9c497c83978ec7759727e0aad0a63ad3b08563eb76924ef4
deleted: sha256:a3f2c24fb962b084feec725069de0404e75770324e69a695ab22a284786a3789
deleted: sha256:d6fcf4c960ee10f84d3fdf461b5fbc3bae35b7a8e24bc44b176b6b447a5ecfc8

Total reclaimed space: 20.74kB

Giving your images a label (see LABEL) and pruning by that label, or by --filter until=24h, is a good habit in CI. Two stronger variants exist; use them with care:

  • docker image prune -a also deletes every image not used by a container, even if it has tags. Great on a throwaway CI runner, dangerous on a development laptop because the next docker run will have to download things again.
  • docker system prune removes stopped containers, unused networks, dangling images and build cache in one go. Cleaning Up covers the whole family and how to automate it safely.

How much space do images use?

docker system df summarizes disk use by type, including how much is reclaimable:

CONSOLE
$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          57        10        13.38GB   926.3MB (6%)
Containers      10        4         6.148GB   1.946MB (0%)
Local Volumes   13        9         1.335GB   310.2MB (23%)
Build Cache     242       4         20.76GB   20.28GB

(These numbers come from a busy development machine; yours will differ.) Active means in use by at least one container. Add -v for a per-image breakdown. On many machines the build cache is the largest item, which surprises people.

docker search queries Docker Hub from the command line:

CONSOLE
$ docker search --limit 3 nginx
NAME                              DESCRIPTION                                     STARS     OFFICIAL
nginx                             Official build of Nginx.                        21409     [OK]
nginx/nginx-ingress               NGINX and  NGINX Plus Ingress Controllers fo…   124       
nginx/nginx-prometheus-exporter   NGINX Prometheus Exporter for NGINX and NGIN…   53        

The [OK] marks a Docker Official Image. Useful options are --limit, --filter is-official=true, --filter stars=100 and --format. The command has limits: it shows names and star counts, but not tags. Search the website for a repository's tag list and its documentation, which tells you what variants (-alpine, -slim, -bookworm) exist and what each is for; we compare them in Choosing a Base Image.

Good habits

  • Pull explicitly to refresh a tag that you use for development; do not assume docker run updates it.
  • Use specific tags (postgres:17-alpine, not postgres) so that your setup behaves the same next month.
  • Remove by name, and containers before images.
  • Prune with filters on any shared machine, and automate cleanups on build servers.
  • Watch docker system df now and then. Disk-full errors in Docker usually come from images, build cache or unrotated container logs (Common Docker Errors).

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. You ran 'docker run nginx' last month. Today the nginx maintainers published a security update under the same tag. What happens when you run 'docker run nginx' again?

    docker run only pulls when the image is missing locally. Use docker pull nginx (or docker run --pull always) to refresh a tag.
  2. 2. What does 'Status: Image is up to date for busybox:1.36' mean?

    Docker compares the manifest digest the tag points to on the registry with the local one. Equal digests mean there is nothing to fetch.
  3. 3. You have two tags, app:1 and app:stable, pointing to the same image. What does 'docker rmi app:1' do?

    rmi removes names. The image content is deleted only when its last name is gone and no container still uses it.
  4. 4. What is a dangling image?

    A dangling image has no name any more, typically because a tag was moved to a newer build. It is safe to prune if nothing needs it.
  5. 5. Which command removes dangling images only from your own project, without touching other people's images on a shared machine?

    Filters such as label= or until= restrict prune to matching images. Plain or -a variants affect everything that qualifies on the machine.

Summary

  • docker pull NAME[:TAG|@DIGEST] downloads missing layers and reports the manifest digest; a repeated pull says Image is up to date when the tag has not moved.
  • docker run pulls only when the image is absent, so it never refreshes an existing tag by itself.
  • docker images lists tags with ID, disk usage and content size; filter with --filter reference=, dangling=true, label=, and shape output with --format or -q.
  • docker tag adds a name to an image without copying data; several names can share one ID.
  • docker rmi removes names; layers go when the last name is gone and no container uses the image. Remove containers first, and avoid -f unless you understand the result.
  • Dangling images have no tag; clean them with docker image prune, preferably with a --filter on shared machines.
  • docker system df shows what uses disk space, and docker search finds repositories on Docker Hub (names and stars, not tags).

Next: Layers and the Union Filesystem