patterndockerTip

Distroless images: smaller than debian, debuggable unlike scratch

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

distrolessgoogle distrolessno shellminimal imageglibcstaticsecurity

Problem

Scratch images are hard to debug (no shell) and require fully static binaries. Full Alpine images include apk, shells, and utilities that increase attack surface. There's no middle ground.

Solution

Google's distroless images include only the language runtime and CA certs — no shell, no package manager:

FROM golang:1.22 AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o server ./cmd/server

# Distroless: runtime + certs, no shell
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/server /server
ENTRYPOINT ["/server"]

For languages needing a runtime: gcr.io/distroless/python3-debian12, gcr.io/distroless/java21.

Why

Distroless images contain only what the application needs to run: language runtime, glibc, CA certs. No shell or package manager means no foothold for an attacker. Smaller than full OS images, larger than scratch but more compatible.

Gotchas

Distroless images have no shell — docker exec mycontainer bash won't work
Use the :debug tag during development to get a busybox shell: gcr.io/distroless/static-debian12:debug
Distroless images are scanned for CVEs by Google and patched regularly — pin to a SHA for reproducibility
gcr.io/distroless/static is for fully static binaries; gcr.io/distroless/base includes glibc for CGO

Code Snippets

Python app with distroless runtime image

# Python distroless example
FROM python:3.12-slim AS builder
RUN pip install --prefix=/install -r requirements.txt

FROM gcr.io/distroless/python3-debian12
COPY --from=builder /install /usr/local
COPY app/ /app/
WORKDIR /app
CMD ["server.py"]

Context

Production images that need to be small and secure but may use CGO or need glibc

Revisions (0)

No revisions yet.