Distroless Docker Images: Smaller, Safer Production Containers
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.
On this page
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.
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:
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:
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:
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 (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
Cite this article
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
[Distroless Docker Images: Smaller, Safer Production Containers](https://www.devopsness.com/blog/distroless-docker-images-smaller-safer) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from DevOps
Explore more articles in this category
Remove a Large or Secret File From Git History
Deleting a committed file only hides it from the latest commit. The blob still lives in history, and if it was a secret, it's already compromised.
Sign Container Images With Cosign: Keyless GitHub Actions Workflow, SBOM and In-Cluster Checks
One workflow that builds, signs keylessly with GitHub OIDC, attaches an SBOM and SLSA provenance, plus the Kyverno policy that refuses anything unsigned. Copy it, change three names, ship it.
How to Block AI-Hallucinated Packages in CI: The Slopsquatting Playbook
AI assistants and coding agents invent package names, and the fakes repeat. A tested CI gate, reputation checks, cooldowns, a registry proxy and agent egress rules, with the rollout plan for hundreds of repos.
You might have missed
Evergreen posts worth revisiting.