How to shrink a container image

A working container image can be a few kilobytes: build a statically linked server binary, copy it into an empty scratch image, and skip the operating system entirely. In a test on 2026-11-08, a tiny C web server built this way measured 5,174 bytes in a registry with a static musl build, and 2,361 bytes with a freestanding binary that calls Linux syscalls directly. Both images served a page.

That is unusual. A typical container image is dominated by a base operating system and a language runtime, not by the app's own files. The question is useful because image size affects how fast a host can pull and start an app, and how much registry storage repeated deploys accumulate.

What an image is made of

An OCI image is a manifest, a config file, and one or more layers; the layers hold the filesystem. The OCI Image Specification defines the manifest and config as JSON, and each layer as a tar archive, usually gzip-compressed. A registry stores the compressed layers plus that metadata (checked 2026-11-08).

In a normal image, the first and largest layer is the base OS: Debian, Ubuntu, Alpine, a Python image, a Node image. Each later layer adds changes: your code, installed packages, build output. A multi-stage build keeps the compiler and package cache in an earlier stage and copies only the result into the final stage, so they never enter the last image (Docker, multi-stage builds, checked 2026-11-08).

The floor is the OCI metadata itself: a manifest, a config, and at least one layer. This is why the two measurements above do not shrink to zero: the 2.36 KB image is mostly that metadata plus a very small binary, not an operating system.

The recipe

Use a builder stage to compile a static binary, then copy that one file into scratch. scratch is Docker's reserved empty base image: no shell, no libc, no package manager, no /etc (Docker, base images, checked 2026-11-08). The program must therefore be statically linked and self-contained.

A portable version, using Alpine's musl toolchain in the builder:

FROM alpine:3.20 AS build
RUN apk add --no-cache gcc musl-dev
COPY server.c /server.c
RUN cc -Os -static -s -o /server /server.c

FROM scratch
COPY --from=build /server /server
USER 65534:65534
EXPOSE 8080
ENTRYPOINT ["/server"]

The final image has one layer: /server. -Os optimises for size, -static removes the runtime library dependency, and -s strips symbols. The server itself must listen on the port the host routes to, bind to 0.0.0.0 rather than 127.0.0.1, and handle the host's health checks.

Smaller still is possible by removing the C library as well: a freestanding x86_64 program can make the socket, bind, listen, accept, recv, send, shutdown and close syscalls directly, with -nostdlib -nostartfiles. That is the 2,361-byte version, but it is architecture-specific and harder to maintain.

What you give up

A scratch image has no operating system to fall back on. There is no shell, so a health check like CMD curl -f localhost cannot run; the check must be the app's own endpoint, or the host must probe it over HTTP. There are no CA certificates, so outbound HTTPS needs a certificate file copied in. There is no timezone database, no package manager, and no libc for dynamically linked tools. Debugging usually means adding a temporary shell stage or reading logs.

The image is also fixed at build time. Security updates require rebuilding and redeploying, and a static binary must match the host's CPU architecture. For a small service that only serves a page or an API, these are acceptable trade-offs. For an app that shells out, installs packages at runtime, or depends on system libraries, a normal base image is the right choice.

How to measure the stored size

Measure at the registry, in bytes, and say whether the number is compressed. A local docker images figure can differ from what the registry stores and what the host pulls. The most direct check is the registry's manifest: the manifest lists each layer's compressed size, and the config carries the rest. Docker's docker buildx imagetools inspect and tools such as crane manifest read the same data.

As a disclosed example, Cloudish (the host made by Hal9, which started this wiki) builds an uploaded source tarball server-side and pushes the result to its own registry, so there is no local Docker daemon to measure (Cloudish, skill.md, checked 2026-11-08). Its GET /api/v1/images/registry returns one entry per repository with a size field, described as the total bytes across all tags (Cloudish OpenAPI, checked 2026-11-08). In the test, that field read 5,174 and 2,361 bytes; the platform's own image-pull event for each app reported the same two numbers.

One caveat when comparing builds: the size is per repository, not per image. Each deploy can add a tag to the same repository, so the total grows with every retained build. Deleting old tags reclaims the space; the same registry API exposes tag deletion.

What it costs

Registry storage is charged by bytes, so a kilobyte-scale image is negligible; compute time is the real cost. Cloudish's published rates illustrate the split (all checked 2026-11-08): an image build runs at the build's own size, with the default 3 CPU / 5 GB costing about $0.0023 per minute (Cloudish, instances.md), while the smallest always-awake app size, shared, costs $0.010733 per hour. The pricing response lists compute and domain rates and has no registry-storage line (Cloudish pricing API, checked 2026-11-08), so on this rate card the image bytes add no separately-priced charge.

Even if a registry charged per gigabyte-month, the arithmetic is small: 1,000 images at 2.4 KB each is about 2.4 MB, and 1,000,000 is about 2.4 GB. Build time and running time dominate. The practical reason to shrink an image is faster pulls, faster cold starts, and a smaller surface to audit, not the storage bill.

See also

Glossary terms used on this page: API, Container, Deploy, Host, Logs, Tool.

Sources

All checked on 2026-11-08.


First version written with AI assistance and checked against the sources on 2026-11-08. Found a mistake? Fix it or open an issue. Text licensed under CC BY 4.0.