Skip to main content
Distroless Docker Images: Smaller, Safer Production Containers

Distroless Docker Images: Smaller, Safer Production Containers

KU
· Founder & Chief Editor
• 7 min read•Updated •16 views

Our node image shipped 240 CVEs, most from OS packages we never called. Moving to distroless dropped the count to single digits and cut image size by 70%.

Key takeaways

  • Distroless images ship only your app and its runtime, with no shell or package manager, so scanners find far fewer OS-level CVEs.
  • Build in a normal image, copy the output into gcr.io/distroless with a multi-stage Dockerfile, and use the nonroot tag.
  • Debug with kubectl debug ephemeral containers, since there is no shell to exec into.

Distroless images contain only your application and its runtime dependencies: no shell, no package manager, no coreutils. You build in a full image and copy the result into a base like gcr.io/distroless/nodejs24-debian13:nonroot with a multi-stage Dockerfile. The payoff is fewer OS-level CVEs and a smaller image; the cost is debugging without a shell.

Verified against

Distroless Debian 13 (trixie) images (static-debian13, base-debian13, nodejs22/24-debian13) and Kubernetes ephemeral containers (stable since v1.25), against the GoogleContainerTools/distroless README, its base image README, and the kubernetes.io debug-running-pod task page. Checked October 2026.

A quarterly security scan flagged our checkout service with a couple of hundred known vulnerabilities. I spent an afternoon triaging them and realized something annoying: almost none were in our code or our dependencies. They were in bash, apt, perl, and a pile of shared libraries that came free with the official Node image. Our app never invoked a shell. We were carrying a full Debian userland to run a single Node process.

That's the case for distroless. You ship the language runtime and your app, and nothing else. The attack surface shrinks because most of it was never yours to begin with.

What the scan looks like before and after

Scan both builds of the same service and compare. We use Trivy; container vulnerability scanning compares it with the alternatives.

Bash
trivy image --severity HIGH,CRITICAL checkout:slim
trivy image --severity HIGH,CRITICAL checkout:distroless

On our service the HIGH and CRITICAL count fell from dozens to single digits, and the image shrank to roughly a third of its -slim size. Your numbers will differ with the base image and the scan date, so measure your own. What was left were findings in a transitive npm dependency, which is exactly where I want my attention to go. Signal instead of noise.

The build

Distroless has no way to install anything, so you build in a normal image and copy the result across. Multi-stage does the work:

Dockerfile
FROM node:24-trixie AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM gcr.io/distroless/nodejs24-debian13:nonroot
WORKDIR /app
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
EXPOSE 3000
CMD ["dist/server.js"]

Three details matter. First, match the Debian release: build on a trixie-based image when the runtime is -debian13, so any native modules link against the same glibc. Second, the nonroot tag runs the container as a non-root nonroot user, which you want regardless of distroless. Third, CMD takes no shell form. There's no /bin/sh, so CMD npm start won't work. For the nodejs images the entrypoint is already node, so the CMD is just the script path.

Pick the image tag from the current list. As of October 2026 the project publishes only Debian 13 images, with Node.js 22, 24 and 26, Python 3, and Java 17, 21 and 25 variants, each tagged latest, nonroot, debug and debug-nonroot. The README says any other tags are deprecated and no longer updated, so a Dockerfile still pinned to nodejs20-debian12 is quietly drifting out of patch coverage.

Debugging when there's no shell

The first time an on-call engineer tried kubectl exec -it pod -- sh against a distroless pod, they got an exec error saying the executable wasn't found and pinged me in a panic thinking the container was corrupt. It wasn't. There's simply no shell to exec into. That's the tradeoff, and it's worth naming loudly to your team before it bites them at 2am.

Two ways out. During development, use the debug variant of the image, which adds a BusyBox shell:

Dockerfile.debug
FROM gcr.io/distroless/nodejs24-debian13:debug-nonroot

In production, keep the lean image and attach an ephemeral debug container instead. Ephemeral containers have been stable since Kubernetes v1.25:

Bash
kubectl debug -it checkout-7d9f --image=busybox:1.37 --target=checkout -- sh

--target puts the BusyBox shell in the process namespace of the running container, so you can inspect /proc, check open file descriptors, and poke the network without ever adding tooling to the production image. The Kubernetes docs note that the container runtime must support --target; if it doesn't, the debug container may start with an isolated process namespace where ps shows nothing useful. The kubectl debugging commands post covers the rest of the toolkit.

The CA cert and timezone traps

These are the two things that come free in a normal base image and bite when they're missing, and both fail in ways that look like application bugs. The good news is that the distroless project already handles them: per the base image README, gcr.io/distroless/static contains ca-certificates, tzdata, a /etc/passwd entry for root and a /tmp directory, and base adds glibc and libssl on top.

The trap is what people reach for next. Go teams often move from distroless/static to FROM scratch to shave the last couple of MiB, and scratch has none of that. Outbound HTTPS then fails with x509: certificate signed by unknown authority, and time.LoadLocation("America/New_York") returns an error. If you go to scratch, copy the bundle from the build stage and embed tzdata in the binary:

Dockerfile
# Dockerfile (scratch variant)
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

For Go, import time/tzdata or build with -tags timetzdata to embed the zone database. Or just stay on distroless/static-debian13, which is around 2 MiB and already has both.

Questions people ask

How do I get a shell in a distroless container?

You can't, because there isn't one. Use the :debug or :debug-nonroot tag, which adds a BusyBox shell, for local development. In Kubernetes production, attach an ephemeral container with kubectl debug -it <pod> --image=busybox --target=<container> -- sh. It shares the target's process namespace, so you can inspect /proc and the network without changing the production image.

What is the difference between distroless static and base?

gcr.io/distroless/static holds ca-certificates, tzdata, a root /etc/passwd entry and /tmp, and suits fully static binaries such as Go built with CGO_ENABLED=0. gcr.io/distroless/base adds glibc and libssl for dynamically linked programs. Language images like nodejs24-debian13 and python3-debian13 build on those and add the runtime, so you rarely pick base directly.

Are distroless images based on Debian 12 or Debian 13?

As of October 2026 the distroless project publishes Debian 13 (trixie) images only, such as static-debian13, base-debian13 and nodejs24-debian13. Its README states that any tags other than latest, nonroot, debug and debug-nonroot on the listed images are deprecated and no longer updated, so Dockerfiles that still reference -debian12 images should be migrated.

The call we'd make

For compiled languages, Go and Rust especially, go straight to distroless/static-debian13 and don't look back; it already carries the CA bundle and tzdata that scratch makes you copy by hand. For Node, Python, and Java, distroless is still my default for anything customer-facing, because a large CVE reduction and a smaller image are not a hard sell to anyone who's sat through a compliance review. The one place I'd hesitate is a team with no container debugging discipline yet. If nobody knows kubectl debug exists, a shell-less image turns every incident into a longer incident. Teach that first, then switch the base image.

Sources

Explore topics:DockerSecurityDevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). Distroless Docker Images: Smaller, Safer Production Containers. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/distroless-docker-images-smaller-safer

Markdown

[Distroless Docker Images: Smaller, Safer Production Containers](https://www.devopsness.com/blog/distroless-docker-images-smaller-safer) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

605 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.