distroless README

The project's README from github.com/GoogleContainerTools/distroless. As one markdown file: README.md.

"Distroless" Container Images.

CI Build Status

"Distroless" images contain only your application and its runtime dependencies. They do not contain package managers, shells or any other programs you would expect to find in a standard Linux distribution.

For more information, see this talk (video).

Why should I use distroless images?

Restricting what's in your runtime container to precisely what's necessary for your app is a best practice employed by Google and other tech giants that have used containers in production for many years. It improves the signal to noise of scanners (e.g. CVE) and reduces the burden of establishing provenance to just what you need.

Distroless images are very small. The smallest distroless image, gcr.io/distroless/static-debian13, is around 2 MiB. That's about 50% of the size of alpine (~5 MiB), and less than 2% of the size of debian (124 MiB).

How do I use distroless images?

These images are built using bazel, but they can also be used through other Docker image build tooling.

What images are available?

The following images are currently published and updated by the distroless project (see SUPPORT_POLICY.md for support timelines)

These images refer to image indexes with references to all supported architectures. Architecture specific images can be directly referenced using an additional architecture suffix on the tag, like gcr.io/distroless/static-debian13:latest-amd64

Any other tags are considered deprecated and are no longer updated

Debian 13

Debian 13 distroless images use the debian UsrMerge scheme. If you use rules_distroless to add packages to an image, set mergedusr = True in apt.install.

Image Tags Architecture Suffixes
gcr.io/distroless/static-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, arm, s390x, ppc64le, riscv64
gcr.io/distroless/base-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, arm, s390x, ppc64le, riscv64
gcr.io/distroless/base-nossl-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, arm, s390x, ppc64le, riscv64
gcr.io/distroless/cc-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, arm, s390x, ppc64le, riscv64
gcr.io/distroless/java-base-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, s390x, ppc64le, riscv64
gcr.io/distroless/java17-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, s390x, ppc64le, riscv64
gcr.io/distroless/java21-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, s390x, ppc64le, riscv64
gcr.io/distroless/java25-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, s390x, ppc64le, riscv64
gcr.io/distroless/nodejs22-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, arm, s390x, ppc64le
gcr.io/distroless/nodejs24-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, s390x, ppc64le
gcr.io/distroless/nodejs26-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, s390x, ppc64le
gcr.io/distroless/python3-debian13 latest, nonroot, debug, debug-nonroot amd64, arm64, riscv64

Why is distroless still using gcr.io instead of pkg.dev?

Distroless's serving infrastructure has moved to artifact registry but we still use the gcr.io domain. Users will get the benefits of the newer infrastructure without changing their builds.

How do I verify distroless images?

All distroless images are signed by cosign with ephemeral keys (keyless). We recommend verifying any distroless image you use before building your image. You can verify the keyless signature of any distroless image with:

cosign verify $IMAGE_NAME --certificate-oidc-issuer https://accounts.google.com --certificate-identity [email protected]

Entrypoints

Note that distroless images by default do not contain a shell. That means the Dockerfile ENTRYPOINT command, when defined, must be specified in vector form, to avoid the container runtime prefixing with a shell.

This works:

ENTRYPOINT ["myapp"]

But this does not work:

ENTRYPOINT "myapp"

For the same reasons, if the entrypoint is set to the empty vector, the CMD command should be specified in vector form (see examples below). Note that by default static, base and cc images have the empty vector entrypoint. Images with an included language runtime have a language specific default (see: java, nodejs, python3).

Docker

Docker multi-stage builds make using distroless images easy. Follow these steps to get started:

Examples with Docker

Here's a quick example for go:

# Start by building the application.
FROM golang:1.18 as build

WORKDIR /go/src/app
COPY . .

RUN go mod download
RUN CGO_ENABLED=0 go build -o /go/bin/app

# Now copy it into our base image.
FROM gcr.io/distroless/static-debian13
COPY --from=build /go/bin/app /
CMD ["/app"]

You can find other examples here:

To run any example, go to the directory for the language and run:

docker build -t myapp .
docker run -t myapp

To run the Node.js Express example app and expose the container's ports:

npm install # Install express and its transitive dependencies
docker build -t myexpressapp . # Normal build command
docker run -p 3000:3000 -t myexpressapp

This should expose the Express application to your localhost:3000

Bazel

For full documentation on how to use bazel to generate Container images, see the bazel-contrib/rules_oci repository.

For documentation and example on how to create custom container images, see the GoogleContainerTools/rules_distroless repository.

Examples can be found in the GoogleContainerTools/rules_distroless repository.

Examples with Bazel

We have some examples on how to run some common application stacks in the /examples directory. See here for:

See here for examples on how to complete some common tasks in your image:

See here for more information on how these images are built and released.

Base Operating System

Distroless images are based on Debian 13 (trixie). Images are explicitly tagged with Debian version suffixes (e.g. -debian13). Specifying an image without the distribution will currently select -debian13 images, but that will change in the future to a newer version of Debian. It can be useful to reference the distribution explicitly, to prevent breaking builds when the next Debian version is released.

Operating System Updates for Security Fixes and CVEs

Distroless tracks the upstream Debian releases, using Github actions to automatically generate a pull request when there are updates.

Debug Images

Distroless images are minimal and lack shell access. The :debug image set for each language provides a busybox shell to enter.

For example:

cd examples/python3/

edit the Dockerfile to change the final image to :debug:

FROM gcr.io/distroless/python3-debian13:debug
COPY . /app
WORKDIR /app
CMD ["hello.py", "/etc"]

then build and launch with a shell entrypoint:

docker build -t my_debug_image .

$ docker run --entrypoint=sh -ti my_debug_image

/app # ls
BUILD       Dockerfile  hello.py

Note: If the image you are using already has a tag, for example gcr.io/distroless/java17-debian13:nonroot, use the tag debug-<existing tag> instead, for example gcr.io/distroless/java17-debian13:debug-nonroot.

Note: ldd is not installed in the base image as it's a shell script, you can copy it in or download it.

Who uses Distroless?

If your project uses Distroless, send a PR to add your project here!

Community Discussion

distroless (GoogleContainerTools/distroless)

Searching Database…

23.2K ·GitHub
Distroless
Что это такое?Набор минимальных базовых образов для контейнеров, в которых есть только ваше приложение и его зависимости во время выполнения — без менеджеров пакетов, оболочек и прочих программ, которые обычно есть в полноценном Linux-дистрибутиве.
То есть это не то, что я устанавливаю — что я на самом деле скачиваю?Готовые базовые образы, опубликованные на gcr.io (например, gcr.io/distroless/static-debian13), которые вы используете как финальный этап сборки. Проект собирает их с помощью Bazel, но подойдёт и обычные инструменты Docker.
Как запустить своё приложение на таком образе?Напишите multi-stage сборку в Docker (нужен Docker 17.05+): один этап собирает приложение, а финальный этап копирует артефакты в distroless-образ. Пользователи Bazel могут использовать rules_oci и rules_distroless, а в репозитории есть готовые примеры для Go, Java, Python, Node.js и Rust.
Какие рантаймы для языков есть в этих образах?Образы на основе Debian 13 для статических бинарников, C/C++ (cc), Java 17/21/25, Node.js 22/24/26 и Python 3, плюс базовый образ без ничего и вариант base-nossl. Каждый публикуется в вариантах latest, nonroot, debug и debug-nonroot.
Если внутри нет оболочки, что меняется в моём Dockerfile?ENTRYPOINT нужно писать в векторной (exec) форме, например ENTRYPOINT ['/app/server'], иначе при запуске система попытается подставить перед командой оболочку, которой не существует. У образов static, base и cc точка входа по умолчанию пустая; у языковых образов она своя для каждого языка.
Это подход только для больших компаний, или маленькой команде тоже подойдёт?Воспользоваться может кто угодно — оставлять в рабочем контейнере ровно то, что нужно приложению, — это лучшая практика, которой придерживаются Google и другие технологические гиганты; на этих образах построены такие проекты, как Kubernetes, Knative, Tekton и Teleport.
Какие процессорные архитектуры поддерживаются?Мультиархитектурные индексы образов покрывают amd64, arm64, arm, s390x, ppc64le и riscv64, хотя у отдельных рантаймов наборы немного отличаются. Закрепить конкретную можно суффиксом тега, например :latest-amd64.
Почему стоит выбрать distroless, а не Alpine или slim-образ Debian?Размер и меньше шума от сканеров: самый маленький статический образ весит около 2 МиБ — примерно вдвое меньше Alpine (~5 МиБ) и меньше 2% от Debian (124 МиБ). А поскольку внутри нет оболочки и менеджера пакетов, CVE-сканеры выдают меньше лишних срабатываний, и проще подтвердить происхождение образа.
Как отлаживать контейнер, в котором нет оболочки?Поменяйте тег образа на вариант :debug (или debug-nonroot) — в них добавлена оболочка busybox, в которую можно зайти. Один нюанс: ldd в базовый образ не входит, потому что это скрипт для оболочки.
Почему образы до сих пор лежат на gcr.io?Инфраструктура раздачи уже переехала в Artifact Registry, но distroless сохраняет домен gcr.io, чтобы существующие сборки получали новую инфраструктуру без каких-либо изменений.
Как обеспечивается надёжность и актуальность образов?Каждый образ подписывается с помощью cosign эфемерными (keyless) ключами, и проект рекомендует проверять подпись, прежде чем строить что-то поверх образа. Исправления по безопасности выходят вслед за релизами upstream-Debian, а GitHub Actions автоматически создаёт PR с обновлениями.
What are similar projects?slim, kaniko, portainer, awesome-docker, docker-minecraft-server, containerd, harbor, distribution
Which topics is it in?container-security, bazel, containerization, docker-image, minimal, supply-chain-security, multi-platform, debian, devops-tools, dockerfile, arm64, lightweight
Creator
GoogleContainerTools
Size
10 MB
Stars
23.2K
Updated
CommitOct 17
Age
9y
Commits · 90 Days