# Distroless Docker Images: Smaller, Safer Production Containers

URL: https://www.devopsness.com/blog/distroless-docker-images-smaller-safer
Author: Kiril Urbonas
Published: 2026-07-02
Updated: 2026-10-31
Categories: DevOps
Tags: Docker, Containers, Security, Production, DevOps

Summary: 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%.

---
# Distroless Docker Images: Smaller, Safer Production Containers

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]
> 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](/blog/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
# 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
# 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](/blog/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

- [GoogleContainerTools/distroless README (image list and tags)](https://github.com/GoogleContainerTools/distroless)
- [Distroless base and static image contents](https://github.com/GoogleContainerTools/distroless/blob/main/base/README.md)
- [Kubernetes Docs: Debug running pods (ephemeral containers)](https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/)

