Distroless images ship only your app and its runtime, with no shell or package manager: how they cut attack surface, multi-stage builds and Chainguard images.
Distroless Images, explained by cats. Kitty has a tuna tracking app. She ships it in a Docker image. A Docker image packs kitty's app and its dependencies in one box. Kitty can take that box anywhere. But the box is heavy.
It carries many things. Shells. Package managers. Debug tools. More things also mean more places for bugs to hide. And more attack surface for bad cats to get inside. So Kitty uses a Distroless Image. A distroless image only has the runtime her app needs.
And nothing else. No shell or package manager. But how does kitty get one? She could strip an image down herself. Configure it. Keep it patched. Forever. But that's hard. And Kitty wants a nap. So Kitty uses Chainguard container images.
Chainguard provides Kitty with pre-configured distroless images. Minimal, hardened and rebuilt nightly. Kitty changes one line in her Dockerfile: And now Kitty has a smaller and safer container. Less baggage. Less attack surface. And more protected
A distroless image is a container image that holds your app and the runtime it needs, and nothing else: no shell, no package manager, no debugging tools. Less in the box means less to patch, less to scan and far less for an attacker to work with.
What a typical image carries
Most Dockerfiles start from a general-purpose base such as debian, ubuntu, node or python. Those images are built to be comfortable for people. They ship a full operating system userland: a shell (sh or bash), a package manager (apt or apk), core utilities like ls, cat and grep, and often networking tools such as curl.
That is handy while you develop. You can open a shell in the container, poke around and install something to test a theory. In production, though, your app almost never calls any of it. A web service written in Go needs its binary, CA certificates for talking to HTTPS services and time zone data. A Python app needs the interpreter and its libraries. The shell and the package manager just come along for the ride.
What distroless removes
The name is a little misleading. A distroless image still contains some files from a Linux distribution, because your runtime needs them: a C library to link against, so it knows which user it runs as, and certificates to verify TLS connections. What it drops is everything a person would use to manage the system:
Distroless Images, explained by cats. Kitty has a tuna tracking app. She ships it in a Docker image. A Docker image packs kitty's app and its dependencies in one box. Kitty can take that box anywhere. But the box is heavy.
It carries many things. Shells. Package managers. Debug tools. More things also mean more places for bugs to hide. And more attack surface for bad cats to get inside. So Kitty uses a Distroless Image. A distroless image only has the runtime her app needs.
And nothing else. No shell or package manager. But how does kitty get one? She could strip an image down herself. Configure it. Keep it patched. Forever. But that's hard. And Kitty wants a nap. So Kitty uses Chainguard container images.
Chainguard provides Kitty with pre-configured distroless images. Minimal, hardened and rebuilt nightly. Kitty changes one line in her Dockerfile: And now Kitty has a smaller and safer container. Less baggage. Less attack surface. And more protected
no package manager, so nothing can be installed at runtime
no general-purpose tools like curl, wget or ls
What remains is the smallest set of files that lets one kind of program run. That is why distroless images come in flavours per runtime: a static image for self-contained binaries, and separate images for Python, Java, Node.js and so on.
Try to open a shell in one and it simply fails, because there is no sh to start:
docker run --rm -it --entrypoint sh \ cgr.dev/chainguard/nginx
Why fewer parts means fewer problems
A smaller attack surface
Suppose an attacker finds a bug in your app that lets them run a command. On a full base image, that is the start of a very bad day: they can open a shell, use curl to fetch more tools and use the package manager to install whatever else they need. In a distroless container, the same bug leads to a dead end. There is no shell to spawn and nothing to install with. It doesn't make the bug harmless, but it takes away the tools most attacks lean on next.
Fewer vulnerabilities to chase
Every package in an image is something that can have a known vulnerability, or CVE. Security scanners such as Trivy and Grype report every one they find, whether or not your app ever uses the affected package. A full OS image can produce a long list of CVEs in tools your service never touches, and someone still has to triage each one. Remove the packages and those reports go with them, leaving the ones that matter: your runtime and your own dependencies.
Smaller and quicker to ship
Fewer files means a smaller image, which pulls faster onto new servers and starts sooner when you scale out. That is a pleasant side effect rather than the main reason to switch. The security win is the point.
Where distroless images come from
Building your own base
You can strip an image down yourself, working out exactly which libraries, certificates and config files your runtime needs. It works, but it is a job for life. Those libraries receive security fixes, and each fix means rebuilding, testing and shipping again, for every service, indefinitely. Most teams shouldn't take this on.
Google's distroless images
The project that popularised the term. Google publishes images under gcr.io/distroless, built from Debian packages, with variants such as static, base, python3, java and nodejs. Each has a nonroot tag that runs as an unprivileged user, and a debug tag that adds a BusyBox shell for troubleshooting.
Chainguard images
Chainguard publishes a large catalogue of minimal, hardened images under cgr.dev/chainguard. They are built on Wolfi, Chainguard's own Linux distribution designed for containers, and rebuilt nightly, so fixes to the packages inside arrive without you doing the work. Many images also have a -dev variant that adds a shell and the apk package manager, meant for build stages and debugging rather than production.
For a popular image, switching is often a single line. Here is an nginx web server moving from the official Debian-based image to Chainguard's:
# Before: nginx on a full Debian baseFROM nginx# After: a minimal build of nginxFROM cgr.dev/chainguard/nginx
'Often' matters there: the replacement can use a different default user, port or file layout, so read the image's documentation and test before you ship.
Building your app on a distroless base
You can't run the build itself in a distroless image: compiling needs compilers, package managers and a shell. The standard answer is a multi-stage build. Build in a full image, then copy only the result into a distroless one.
Here is a Go service built that way:
# Stage 1: the full toolchainFROM golang:1.23 AS buildWORKDIR /srcCOPY . .RUN CGO_ENABLED=0 go build -o /app .# Stage 2: only what runsFROM gcr.io/distroless/static-debian12:nonrootCOPY --from=build /app /appENTRYPOINT ["/app"]
The first stage has Go, Git, a shell and everything else a build needs. None of it reaches the final image. CGO_ENABLED=0 tells Go to produce a fully static binary that doesn't need a C library, so it can run on the tiny static image. The nonroot tag runs the app as an unprivileged user instead of root, another cheap layer of defence. With Chainguard, the same pattern uses cgr.dev/chainguard/go for the build stage and cgr.dev/chainguard/static for the final one.
Interpreted languages follow the same shape. For Python, install your dependencies in a full Python image, then copy the installed packages and your code into a distroless Python image that has the interpreter and little else.
Debugging without a shell
The first time something breaks in production, you will reach for a shell that isn't there. Plan for that before it happens:
Lean on logs and metrics. With no way to look around inside the container, good logging stops being optional.
Use a debug variant locally. Google's debug tags and Chainguard's -dev images include a shell. Use them to investigate, but don't ship them.
Attach a debug container. In Kubernetes, kubectl debug adds a temporary container with its own tools next to your app, so the production image stays minimal.
Shell-form commands.CMD python app.py quietly runs through /bin/sh -c, which doesn't exist here. Use the exec form, such as ENTRYPOINT ["/app"].
RUN steps in the final stage. A RUN instruction needs a shell too. Do all installing and compiling in the build stage.
Mismatched language versions. Packages installed for one Python version won't load in an image with another. Match the version exactly between stages.
Never rebuilding. A nightly-rebuilt base only helps if you rebuild and redeploy your own image to pick up the new layers.
Treating it as the whole security story. Your code and your dependencies still need scanning and patching. Distroless shrinks everything around them.
When to use it
Distroless images suit production services, especially anything facing the internet. Compiled languages that produce a single static binary, such as Go and Rust, are the easiest place to start.
They suit local development and CI images less well, since those genuinely need tools. They are also awkward for apps that call other programs at runtime, such as a service that shells out to git or ffmpeg: those programs have to be in the image, which pulls you back towards a fuller base.
Key takeaways
A distroless image holds your app and its runtime, with no shell, package manager or debugging tools.
Fewer packages means a smaller attack surface and fewer irrelevant CVEs to triage.
Build in a full image and copy only the result into a distroless one with a multi-stage build.
Google and Chainguard publish maintained distroless images, so you don't have to patch a base yourself.
Rebuild often, and debug with a debug variant or kubectl debug instead of shipping a shell.