explaingit

googlecontainertools/distroless

📈 Trending22,631StarlarkAudience · ops devopsComplexity · 2/5ActiveLicenseSetup · moderate

TLDR

Minimal Docker images from Google containing only your app and its runtime, no shell, package manager, or extra bloat. Smaller, more secure, harder to debug.

Mindmap

mindmap
  root((repo))
    What it does
      Strips OS bloat
      Reduces image size
      Cuts attack surface
    Key features
      Language variants
      Debug mode available
      Multi-stage compatible
    Use cases
      Production deployments
      Security-critical apps
      Minimal footprint needed
    Trade-offs
      Harder debugging
      No shell access
      Limited troubleshooting

Things people build with this

USE CASE 1

Deploy production applications in containers with minimal security risk and smaller image sizes.

USE CASE 2

Build multi-stage Docker images where you compile in a full environment, then copy only the binary into a distroless runtime.

USE CASE 3

Reduce storage costs and deployment time by cutting container image size from 100+ MB down to 2-10 MB.

USE CASE 4

Harden containerized services against intrusion by removing shells, package managers, and unnecessary system tools.

Tech stack

DockerStarlarkPythonJavaNode.js

Getting it running

Difficulty · moderate Time to first run · 30min

Requires Docker installed and understanding of how to build/run container images; Starlark build rules need Bazel or similar tooling.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice and license text.

In plain English

Distroless is a collection of minimal Docker container images from Google that contain only your application and the specific runtime it needs to run, nothing else. A standard Linux-based Docker image comes bundled with a full operating system including a package manager, a shell, and hundreds of programs and libraries that your app never actually uses. All of that extra software is potential dead weight: more storage, more attack surface for security vulnerabilities, and more noise when security scanners try to flag problems. Distroless strips all of that out. The smallest distroless image is around 2 megabytes, compared to roughly 124 megabytes for a standard Debian image. Because there is no shell or package manager inside the container, there is much less that can go wrong or be exploited if someone breaks in. The practical tradeoff is that debugging becomes harder, you cannot shell into the container and poke around. There is a special "debug" variant of each image that adds a minimal shell for troubleshooting purposes. You would use distroless images when deploying production applications in containers where security, image size, and a minimal footprint matter. They work especially well with the Docker multi-stage build pattern: you use a full build environment to compile your app, then copy only the compiled result into a distroless runtime image. Language-specific variants are available for Python, Java, Node.js, and others.

Copy-paste prompts

Prompt 1
Show me how to convert a Node.js Docker image to use distroless as the base image.
Prompt 2
How do I use distroless with a multi-stage Docker build to compile a Go app and run it in a minimal container?
Prompt 3
What's the difference between a distroless image and a standard Debian image, and when should I use each?
Prompt 4
How do I debug an application running in a distroless container if there's no shell?
Open on GitHub → Explain another repo

Generated 2026-05-18 · Model: sonnet-4-6 · Verify against the repo before relying on details.