Distroless — Minimal Container Images by Google

Introduction

Distroless images contain only your application and its runtime dependencies — no package manager, no shell, no standard Linux utilities. Google created them to reduce the attack surface and image size of production containers, following the principle that the best way to secure a container is to remove everything that is not strictly required.

What Distroless Does

• Provides base images for Java, Python, Node.js, Go, Rust, and static binaries
• Eliminates shell access and package managers from production containers
• Reduces container image size by 50-80% compared to traditional base images
• Minimizes CVE exposure by removing unnecessary OS packages
• Supports nonroot variants for running as non-privileged users out of the box

Architecture Overview

Distroless images are built using Bazel and are based on Debian. Each image variant includes only the language runtime (e.g., glibc, libssl, the JRE) and CA certificates. The build pipeline produces multi-architecture images (amd64, arm64) published to Google Container Registry. Images are rebuilt and scanned for vulnerabilities on a regular cadence.

Self-Hosting & Configuration

• Pull images from gcr.io/distroless/ or mirror to your own registry
• Choose the right variant: static for Go/Rust, base for C/C++, java21-debian12 for JVM apps
• Use multi-stage Docker builds: compile in a full image, copy artifacts into distroless
• Append :nonroot tag to run as UID 65534 without extra Dockerfile configuration
• Debug variants (:debug) include a BusyBox shell for troubleshooting during development

Key Features

• Minimal CVE footprint — fewer packages means fewer vulnerabilities to patch
• Deterministic builds via Bazel ensure reproducible images across CI runs
• Multi-arch support for amd64 and arm64 workloads
• Nonroot-by-default variants enforce least-privilege at the image level
• Broad language coverage from statically linked binaries to JVM and Node.js runtimes

Comparison with Similar Tools

• Alpine Linux — smaller than Debian but still ships a shell and package manager; distroless removes both
• Scratch — truly empty, but distroless adds CA certs, timezone data, and glibc for broader compatibility
• Chainguard Images — similar philosophy with Wolfi OS base; distroless uses Debian and Bazel
• Slim Toolkit — trims existing images by profiling; distroless starts minimal by design
• UBI Micro (Red Hat) — minimal RHEL base; distroless targets Debian and offers more language variants

FAQ

Q: Can I install packages in a distroless image? A: No. There is no package manager. Add all dependencies in a prior build stage and copy them in.

Q: How do I debug a running distroless container? A: Use the :debug tag variant which includes a BusyBox shell, or attach an ephemeral container via kubectl debug.

Q: Are distroless images updated for security patches? A: Yes. Google rebuilds images regularly and publishes updated tags to gcr.io.

Q: Do distroless images work with Kubernetes? A: Absolutely. They are designed for Kubernetes workloads and work with any container orchestrator.

Sources

• https://github.com/GoogleContainerTools/distroless
• https://github.com/GoogleContainerTools/distroless/blob/main/README.md