Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 111 ยท Images

Choosing a Base Image

Compare Docker base images: debian, ubuntu, alpine, slim variants, distroless and scratch. Learn the size vs. compatibility trade-offs, musl vs. glibc, and a decision guide.

The first line of nearly every Dockerfile is FROM something, and that "something" decides a lot: how big your image is, how many security fixes you inherit, which tools exist for debugging, and whether your compiled dependencies work at all. Beginners often pick ubuntu out of habit or alpine because "it is the smallest". Neither is always right.

This lesson compares the common choices side by side with real sizes from our machine, explains the one technical difference that causes most surprises (musl vs. glibc), shows what happens in scratch and distroless images where there is no shell, and ends with a decision guide you can apply to any project.

What a base image provides

A base image is the starting filesystem that your Dockerfile builds on. It does not include a kernel (containers use the host's), only the user-space part of an operating system:

  • the C library (libc) that every dynamically linked program needs,
  • core tools (ls, cp, a shell) and sometimes a package manager (apt, apk),
  • CA certificates, time zone data and a handful of configuration files.

Language images such as python:3-slim or node:lts-alpine are built on top of an OS base and add the runtime. In both cases the question is the same: how much of an operating system do you want to ship with your program? More means convenience and compatibility; less means a smaller image and a smaller attack surface.

The contenders, measured

We pulled each of these and read the DISK USAGE column from docker images (the unpacked size on disk; the compressed download is smaller, and the numbers change as images are updated):

Image Size What it is
debian:bookworm 185 MB Full Debian 12 userland, glibc, apt
ubuntu:24.04 119 MB Ubuntu LTS, glibc, apt
debian:bookworm-slim 116 MB Debian without docs, man pages and extras
gcr.io/distroless/base-debian12 33.1 MB glibc, certificates, no shell, no package manager
alpine:3 13 MB musl libc, BusyBox, apk
busybox:1.37 6.77 MB BusyBox tools only (dynamically linked, glibc)
gcr.io/distroless/static-debian12 6.18 MB Certificates and time zone data only, for static binaries
scratch 0 Literally empty

Language images show the same spread. Both of these contain Python 3.15:

CONSOLE
$ docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep python
python:3-alpine 81.5MB
python:3-slim 184MB

Notice that slim is not "tiny": most of its 184 MB is the Debian layer underneath, with Python on top. Alpine's saving is real here (about 100 MB), but it comes with trade-offs we are about to see.

Debian and Ubuntu

debian and ubuntu are the "just works" family. They use glibc, the C library that almost all prebuilt Linux software targets, and they come with apt, which has a package for nearly everything. Their drawbacks are size and a larger default package set (more software means more potential vulnerabilities to patch).

Debian images come in these flavors:

  • debian:bookworm (the default): the fullest of the three, 185 MB here.
  • debian:bookworm-slim: the same distribution without documentation and other non-essential files, 116 MB here. For most production images this is the sweet spot.
  • Named releases (bookworm, trixie) vs. stable/latest: use the codename you tested against so a new Debian release does not surprise you. Language images follow Debian releases too: python:3-slim is currently based on Debian 13 ("trixie"), as cat /etc/os-release inside it tells you.

Ubuntu offers long-term-support releases (22.04, 24.04) with a familiar environment and is a natural choice when your team already deploys on Ubuntu servers. Prefer a specific tag like ubuntu:24.04 over latest.

Alpine

Alpine Linux is built around two ideas: musl libc instead of glibc, and BusyBox instead of GNU coreutils. Both are far smaller. The result is the famous 13 MB base. Adding a real tool is cheap too:

CONSOLE
$ docker run --rm alpine sh -c 'apk add --no-cache curl 2>&1 | tail -2'
Executing busybox-1.37.0-r31.trigger
OK: 13.1 MiB in 25 packages

Alpine's package manager is apk; --no-cache avoids storing the package index in the layer. Here is what installing curl costs on three bases, using Dockerfiles with the usual cleanup in the same layer (see Layers and the Union Filesystem):

DOCKERFILE
FROM alpine
RUN apk add --no-cache curl
DOCKERFILE
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
 && rm -rf /var/lib/apt/lists/*
CONSOLE
$ docker images --filter reference='tcd-curl-*' --format 'table {{.Repository}}\t{{.Size}}'
REPOSITORY        SIZE
tcd-curl-debian   208MB
tcd-curl-slim     134MB
tcd-curl-alpine   20.8MB

(The tcd-curl-debian row uses the full debian:bookworm with a plain apt-get install -y curl; the other two are the Dockerfiles above.) For tool-style images, Alpine is hard to beat on size.

musl vs. glibc: the compatibility catch

Every dynamically linked Linux program asks a C library to do its work. Programs built against glibc expect glibc's loader and symbols; musl provides different ones. A binary compiled for glibc usually cannot run on Alpine, and the error is cryptic. We copied a normal Debian id binary into an Alpine image:

CONSOLE
$ docker run --rm tcd-glibc-on-alpine
exec /usr/local/bin/id-glibc: no such file or directory

The file exists; what is missing is its interpreter, the glibc dynamic loader (/lib64/ld-linux-x86-64.so.2) that the binary names in its header. The same file runs fine on a glibc image:

CONSOLE
$ docker run --rm tcd-glibc-on-debian
uid=0(root) gid=0(root) groups=0(root)

This is the heart of the Alpine trade-off. It affects:

  • Prebuilt binaries downloaded from a vendor or copied from another stage: they must be built for musl (or be fully static).
  • Language packages with native code, such as Python wheels, Node native addons or Java JNI libraries. Most ecosystems now publish musl builds, but not all, and when one is missing the package compiles from source, which needs a compiler in the image and can make the build slow.
  • Behavioral differences: musl's DNS resolver, locale support and memory allocator differ from glibc's, which occasionally causes odd bugs and, for some workloads, different performance. Always test your real application on the base you will ship.
  • Tooling: BusyBox sh is not bash, and many scripts use bashisms.

Alpine is a great fit for Go/Rust static binaries, small utilities and apps in ecosystems with first-class musl support (Node.js and Python work well for pure-JavaScript/pure-Python dependencies). For a dependency-heavy data-science or machine-learning stack, debian-slim saves you time even though it is bigger.

slim vs. alpine in practice

Debian slim Alpine
Base size ~116 MB ~13 MB
C library glibc (compatible with almost everything) musl (occasional incompatibility)
Shell and tools bash, GNU coreutils BusyBox sh only (ps and wget yes; bash, curl no)
Packages apt, huge repositories apk, smaller but good repositories
Debugging experience Familiar Spartan

We checked the tools inside both images. Alpine has ps and wget (BusyBox applets) but neither bash nor curl; Debian slim has bash but neither ps nor curl nor wget. Neither contains everything you may want when debugging, which leads to the next two options.

scratch: nothing at all

scratch is a special empty base. A FROM scratch image contains only what you COPY in. That is only useful for statically linked programs that need nothing from the OS: no libc, no loader, no shell. Go (with CGO_ENABLED=0) and Rust (with a musl target) produce such binaries. To try the idea without a compiler, we used the static BusyBox from the busybox:musl image (file reports it as "static-pie linked"):

DOCKERFILE
FROM scratch
COPY busybox /busybox
CMD ["/busybox", "echo", "hello from scratch"]
CONSOLE
$ docker build -t tcd-scratch .
$ docker images tcd-scratch
IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
tcd-scratch:latest      74b00c70b0a0       2.03MB          788kB
$ docker run --rm tcd-scratch
hello from scratch
$ docker run --rm --entrypoint /busybox tcd-scratch ls /
busybox
dev
etc
proc
sys

A 2 MB image that starts in milliseconds, and the only things on its filesystem are our one file plus the empty mount points Docker creates (dev, etc, proc, sys). The downsides are the flip side of that minimalism:

CONSOLE
$ docker run --rm tcd-scratch /bin/sh
docker: Error response from daemon: failed to create task for container: ... exec: "/bin/sh": stat /bin/sh: no such file or directory

There is no shell to exec into, no CA certificates (so HTTPS calls from your program fail unless you copy /etc/ssl/certs/ca-certificates.crt in), no time zone database, no /etc/passwd (copy one in if you want a named non-root user). Project: A Tiny Go Image builds a real scratch image step by step.

Distroless: runtime without the OS tools

Google's distroless images sit between Debian and scratch. They contain just enough for a program to run: glibc (in base), CA certificates, time zone data and a non-root user, but no shell, no package manager, no ls. There are variants for static binaries (static), C programs (base, cc) and language runtimes (Java, Python, Node.js).

CONSOLE
$ docker run --rm --entrypoint sh gcr.io/distroless/static-debian12
docker: Error response from daemon: failed to create task for container: ... exec: "sh": executable file not found in $PATH
$ docker image inspect gcr.io/distroless/static-debian12 -f '{{.Config.User}} {{.Config.Entrypoint}} {{.Config.Cmd}}'
0 [] []

Without a shell, an attacker who breaks into your app cannot easily use it to explore, download tools or run commands, and the image has far fewer packages to be flagged by vulnerability scanners. The cost is debugging: you cannot docker exec -it ... sh. You debug with a sidecar container, docker debug or by building a parallel image with the :debug tag (which includes BusyBox); Debugging Containers shows the patterns. Distroless is usually used as the final stage of a multi-stage build (Multi-Stage Builds).

The static image above reports user 0 (root) as its default. Distroless provides :nonroot tags and a nonroot user (UID 65532) for you to use explicitly. Do not assume small images are automatically non-root; set the user yourself (Users and Permissions).

Tags, versions and updates

Whichever family you choose, three habits apply:

  1. Pin a version tag. FROM python:3.15-slim is predictable; FROM python can jump to a new major version at the next build. For strictly reproducible builds, also pin the digest (FROM python:3.15-slim@sha256:...), as discussed in Understanding Images.
  2. Rebuild regularly. The OS packages in a base image are fixed at build time. Security fixes arrive only when you pull the updated base and rebuild. A "small" image you never rebuild is worse than a larger one you refresh weekly.
  3. Know the suffixes. For most official images: -slim (Debian minus extras), -alpine (Alpine), -bookworm/-trixie (Debian release), -bullseye (older release), plus runtime-specific ones like -jre or -windowsservercore. Read the "Supported tags" section of the image's page.

A decision guide

Ask these questions in order:

  1. Is your program a static binary (Go, Rust, some C)? Use scratch or distroless/static for production, built in a multi-stage Dockerfile. Use a normal image for development.
  2. Do you want minimal runtime with a smaller attack surface for a dynamic app (Java, Python, Node, .NET)? Consider the distroless runtime variant, or the -slim/-alpine language image if you need a shell.
  3. Do you rely on native libraries, wheels, or vendor binaries built for glibc? Choose debian-slim (or ubuntu). This is the safe default for most teams.
  4. Is image size, pull time and simplicity your priority, and your dependencies are musl-friendly? Choose Alpine.
  5. Do you need full tooling (compilers, debuggers) in a development or CI image? Use the full image (debian:bookworm, python:3), but keep it out of production images.

If you are unsure: start with -slim, measure, and switch only when you have a measured reason. A 100 MB difference rarely matters on a fast network, but a hard-to-debug musl incompatibility can cost a day.

Size is not the same as security. A tiny image with an outdated library can be less safe than a larger, well-patched one. What helps is a small attack surface and regular rebuilds and scanning. See Image Security and Scanning.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You copy a binary compiled on a Debian machine into an Alpine image and get 'exec ...: no such file or directory', although the file is clearly there. What is the cause?

    A dynamically linked glibc binary names /lib64/ld-linux-x86-64.so.2 as its interpreter. Alpine does not have it, so exec reports the loader as missing. Build against musl, link statically or use a glibc base.
  2. 2. Which base images contain no shell, so 'docker exec -it container sh' cannot work?

    scratch is empty and distroless images deliberately leave out shells and package managers. Alpine and Debian have one.
  3. 3. A team ships a Python image with scientific packages that depend on prebuilt glibc wheels. Which base is the safest default?

    glibc-based images are compatible with almost all prebuilt binaries. Alpine can work, but missing musl wheels lead to slow source builds or failures.
  4. 4. Why is a 13 MB Alpine-based image that you built a year ago and never rebuilt not necessarily safer than a 116 MB Debian slim image rebuilt last week?

    An image never updates itself. Smaller means fewer packages to patch, but you still have to rebuild regularly and scan.
  5. 5. Which Dockerfile line gives the most predictable builds?

    A specific version tag keeps the major and minor version stable. Without a tag you get latest, which can change underneath you. A digest pin is stricter still.

Summary

  • A base image provides the user-space of an operating system (libc, core tools, certificates), never a kernel; choose how much of it you want to ship.
  • debian/ubuntu use glibc and apt and are the most compatible; -slim variants remove extras and are a good default for production.
  • Alpine uses musl and BusyBox: tiny (13 MB here) and fine for static binaries and musl-friendly stacks, but glibc binaries and some native packages do not run or need compiling.
  • scratch is empty and works only for static binaries; distroless adds certificates, time zones and a runtime without shell or package manager.
  • Minimal images shrink the attack surface but cost debugging convenience; use multi-stage builds to produce them.
  • Pin version tags (and digests for strict reproducibility), rebuild regularly and scan: size alone does not make an image secure.
  • Unsure? Start with -slim, measure, and switch only for a reason.

Next: Tags and Registries