Querying the Registry

The docker search command queries public repositories, primarily Docker Hub, to locate available images. The basic syntax follows docker search [OPTIONS] <TERM>.

$ docker search postgres
NAME                             DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
postgres                         The PostgreSQL object-relational database sy…   12840     [OK]       
bitnami/postgresql               Bitnami PostgreSQL Docker Image                 180                  [OK]
sameersbn/postgresql             Containerized PostgreSQL server                 150                  [OK]

Filtering results streamlines discovery. The --filter (or -f) flag restricts output based on metadata, while --limit caps the number of returned rows.

# Retrieve only official images with a minimum star count
$ docker search -f is-official=true -f stars=500 --limit 2 postgres
NAME       DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
postgres   The PostgreSQL object-relational database sy…   12840     [OK]       

Key columns in the output include:

• NAME: Repository identifier.
• DESCRIPTION: Brief overview of the software stack.
• STARS: Community engagement metric.
• OFFICIAL: Indicates vendor or Docker-maintained builds.
• AUTOMATED: Denotes images built via automated CI/CD pipelines.

Retrieving Images

Images serve as read-only templates for containers. Fetching them from a registry uses the docker pull command. The full reference format is [REGISTRY_HOST]/[NAMESPACE]/[REPOSITORY]:[TAG]. Omitting the tag defaults to latest.

$ docker pull redis:7-alpine
7-alpine: Pulling from library/redis
a12b4c8d9e0f: Pull complete 
b23c5d6e7f8g: Pull complete 
c34d6e7f8g9h: Pull complete 
Digest: sha256:8f9a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8
Status: Downloaded newer image for redis:7-alpine
docker.io/library/redis:7-alpine

The output details layer downloads, the content-addressable digest, and the final image reference.

Examining Local Storage

List cached images using docker images or docker image ls.

$ docker image ls
REPOSITORY   TAG          IMAGE ID       CREATED        SIZE
redis        7-alpine     a1b2c3d4e5f6   3 weeks ago    32.4MB
httpd        2.4          f6e5d4c3b2a1   5 weeks ago    145MB
python       3.11-slim    1a2b3c4d5e6f   2 months ago   124MB

Column breakdown:

• REPOSITORY: Source namespace.
• TAG: Version identifier.
• IMAGE ID: Unique SHA256 prefix.
• CREATED: Build timestamp.
• SIZE: Logical disk footprint (shared layer are counted once physically).

Useful flags for listing:

# Output only IDs for scripting
$ docker image ls -q
a1b2c3d4e5f6
f6e5d4c3b2a1
1a2b3c4d5e6f

# Include digest hashes
$ docker image ls --digests --format "table {{.Repository}}\t{{.Digest}}\t{{.Size}}"
REPOSITORY   DIGEST                                                                    SIZE
redis        sha256:8f9a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8   32.4MB

For deep inspection, docker inspect returns the complete JSON configuration, including enviroment variables, entrypoints, and layer hashes.

$ docker inspect httpd:2.4 | jq '.[0].Config.Env'
[
  "PATH=/usr/local/apache2/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
  "HTTPD_PREFIX=/usr/local/apache2",
  "HTTPD_VERSION=2.4.57"
]

To trace build steps, docker history reveals the command sequence that generated each layer.

$ docker history redis:7-alpine
IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT
a1b2c3d4e5f6   3 weeks ago    /bin/sh -c #(nop)  CMD ["redis-server"]         0B        
<missing>      3 weeks ago    /bin/sh -c #(nop)  EXPOSE 6379                  0B        
<missing>      3 weeks ago    /bin/sh -c set -ex; apk add --no-cache ...      12.1MB    
<missing>      3 weeks ago    /bin/sh -c #(nop) ADD file:base_layer.tar.gz    7.8MB     

Image Administration

Assigning custom references simplifies deployment workflows. The docker tag command creates a new pointer to an existing image ID without duplicating data.

$ docker tag redis:7-alpine internal-registry.corp/cache/redis:stable
$ docker image ls | grep redis
internal-registry.corp/cache/redis   stable      a1b2c3d4e5f6   3 weeks ago   32.4MB
redis                                7-alpine    a1b2c3d4e5f6   3 weeks ago   32.4MB

Removing unused images reclaims disk space. Use docker rmi or docker image rm.

# Remove by tag
$ docker rmi httpd:2.4
Untagged: httpd:2.4
Untagged: httpd@sha256:...

# Force removal (ignores dependent containers)
$ docker rmi -f python:3.11-slim
Untagged: python:3.11-slim
Deleted: sha256:1a2b3c4d5e6f...

Automated cleanup handles dangling layers and unreferenced images.

# Remove all images not actively used by a container
$ docker image prune -a --force
Deleted Images:
untagged: internal-registry.corp/cache/redis:stable
deleted: sha256:a1b2c3d4e5f6...
Total reclaimed space: 45.2MB

Generating Custom Images

Images can be captured from running containers or imported from filesystem archives.

Snapshotting a Container The docker commit command freezes a container's writable layer into a new image.

$ docker commit -m "Added custom config and utilities" -a "devops-team" 8f7e6d5c4b3a custom-app:v1.0
sha256:9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4k3j2i1h0g9f8e7d6c5b4a3z2y1x0w9v8

Importing Filesystem Archives A raw OS tarball can be converted directly into a base image.

$ cat debian-base.tar.gz | docker import - local/debian:custom
sha256:m1n2b3v4c5x6z7l8k9j0h1g2f3d4s5a6q7w8e9r0t1y2u3i4o5p6

Archiving and Transferring Images

Docker provides two distinct mechanisms for serializing images and containers to tar archives.

Container-Level Export/Import Targets the running filesystem state, discarding build history and metadata.

# Export a live container to a tarball
$ docker ps --format "{{.ID}} {{.Names}}"
4a5b6c7d8e9f web-server-01
$ docker export 4a5b6c7d8e9f > /tmp/web-snapshot.tar

# Import as a fresh image
$ docker import /tmp/web-snapshot.tar archive/web:flat
sha256:p1o2i3u4y5t6r7e8w9q0a1s2d3f4g5h6j7k8l9z0x1c2v3b4n5m6

Image-Level Save/Load Preserves the complete layer stack, history, and tags. Supports bundling multiple references.

# Archive a single image
$ docker save custom-app:v1.0 > /tmp/app-bundle.tar

# Bundle multiple images into one archive
$ docker save -o /tmp/multi-stack.tar redis:7-alpine local/debian:custom

# Restore on a target host
$ docker load -i /tmp/multi-stack.tar
Loaded image: redis:7-alpine
Loaded image: local/debian:custom

Operational Differences