3.3.1.5 Scratch Base Images

Scratch base images provide the absolute minimum possible starting point for a Docker image: an entirely empty filesystem, with nothing pre-installed at all, intended for statically compiled binaries that need no further runtime support from the image itself.

What Scratch Actually Is

scratch is not an actual downloadable image; it is a special, reserved name recognized by the Docker build process to mean "start from nothing," producing an image whose only content is whatever subsequent instructions explicitly add.

FROM scratch
COPY app /app
ENTRYPOINT ["/app"]

This image contains nothing beyond the single copied binary — no shell, no shared libraries, no operating system files of any kind.

Why Scratch Requires a Fully Static Binary

Because there is no filesystem beyond what is explicitly added, any binary placed into a scratch-based image must not depend on dynamically linked shared libraries that would otherwise be provided by a base operating system image.

CGO_ENABLED=0 GOOS=linux go build -o app .

Disabling CGo and producing a statically linked binary, as shown here for a Go application, is a common requirement for an executable to function correctly inside a scratch-based image.

The Smallest Possible Image Size

Because nothing exists in the image beyond what is explicitly added, a scratch-based image is as small as it is technically possible for a container image to be, often just a few megabytes for a typical compiled application.

docker images myapp

Limitations of Using Scratch

Without any shell, debugging a running scratch-based container interactively is not possible in the usual way, since there is no shell to exec into — diagnosing issues typically requires examining logs or rebuilding a separate debug image with additional tooling included.

docker exec myapp sh

This command fails outright against a container with no shell available inside it at all.

Why Scratch Base Images Matter

scratch represents the logical extreme of minimal image construction, useful specifically for statically compiled applications where every byte of unnecessary filesystem content is considered worth eliminating, at the cost of giving up any interactive debugging convenience inside the running container itself.