Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Alpine musl vs Debian slim: DNS Timeouts and Native Builds

musl rejects manylinux wheels and linux-x64-gnu prebuilds, so the installer starts compiling without a toolchain. And ndots:5 in Kubernetes adds five seconds per lookup.

~4 min readDocker
#Docker#Alpine#musl#DNS
3D illustration of two container boxes side by side, one with a compact musl gear and a broken wheel, the other with a larger glibc gear and a DNS path

Introduction & Quick Summary

Symptom. Three failures arrive the first time an image moves to Alpine. pip install starts compiling C sources and dies on fatal error: gcc: No such file or directory or error: subprocess-exited-with-error for a package that installed in one second on a laptop. A Node image crashes at require('sharp') with Error: Could not load the "sharp" module using the linux-x64 runtime or cannot open shared object file: No such file or directory. In Kubernetes, every outbound HTTP call takes exactly five seconds longer than it should, with no error in the log.

Cause. Alpine uses musl libc, not glibc. Prebuilt wheels and native binaries compiled against glibc (manylinux wheels, linux-x64-gnu Node builds, libvips bundles) are not compatible, so the installer falls back to compiling from source — which requires a toolchain Alpine does not include. And musl's resolver handles search domains and A/AAAA lookups differently from glibc: with the default ndots:5 in a Kubernetes pod, a single lookup issues a series of searches that end in timeouts before the correct name resolves.

Fix. Use python:3.x-slim or node:22-bookworm-slim when any dependency ships native binaries, and treat Alpine as a genuine option only for statically linked binaries or pure-Python/pure-JS dependency trees. Where Alpine is required, install the exact build toolchain in a builder stage, pin musl-specific prebuilds, and set ndots:1 for the pod.

Core Mechanics, Signatures & Reproducible Setup

The libc is the whole story. A Python wheel tagged manylinux_2_28_x86_64 links against glibc's libc.so.6; Alpine has no such file. A wheel tagged musllinux_1_2_x86_64 does link against musl, and only projects that publish one install cleanly.

bash
# what the installer actually sees $ docker run --rm python:3.12-alpine python -c "import platform; print(platform.libc_ver())" ('', '') $ docker run --rm python:3.12-slim python -c "import platform; print(platform.libc_ver())" ('glibc', '2.36')
dockerfile
# Alpine that has to compile numpy, psycopg, or cryptography FROM python:3.12-alpine AS build RUN apk add --no-cache build-base libffi-dev openssl-dev postgresql-dev \ && pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt FROM python:3.12-alpine COPY --from=build /wheels /wheels RUN pip install --no-cache-dir --no-index --find-links /wheels /wheels/*.whl

Reproduce the DNS delay without Kubernetes: run a container on a network with a search domain and time one lookup.

bash
docker run --rm --dns 10.96.0.10 alpine sh -c \ 'time getent hosts api.internal.svc.cluster.local'

If the first lookup takes five seconds and the second is instant, the resolver's negative answers are being retried serially — the musl behaviour behind the Kubernetes symptom.

Key Comparison Table

AspectAlpineDebian slim
libcmuslglibc
Base image size~7 MB~75 MB
manylinux wheelsrejectedinstalled
Python native buildsneed build-baseusually prebuilt
Node native moduleslinux-x64-musl neededlinux-x64-gnu
CVE surfacesmaller package setmore packages to patch
getent hosts with ndots:5slow, serialparallel, cached
Shellbusybox ashdash / bash
FailureMessageResolution
Missing toolchaingcc: No such file or directoryapk add build-base in a builder stage
glibc binary on muslno such file or directory though the file existsrebuild against musl, or use slim
Node prebuild mismatchCould not load the "sharp" moduleinstall with --libc=musl or drop Alpine
DNS slowness5s per new hostnamendots:1, or single-request-reopen
Missing zoneinfoTZ has no effectapk add tzdata
ld-linux-x86-64.so.2not found at execthe binary is glibc-linked

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Error: Could not load the "sharp" module using the linux-x64 runtime

Native Node modules ship one prebuilt binary per os/cpu/libc triple. npm installs the one matching the machine doing the install, so a lockfile built on a macOS laptop or a Debian CI runner records linux-x64-gnu and the Alpine runtime looks for a musl build that was never downloaded.

dockerfile
# force the musl variants at install time RUN npm ci --os=linux --cpu=x64 --libc=musl # or keep Alpine out of the runtime image entirely FROM node:22-bookworm-slim

bcrypt, canvas, better-sqlite3, and sharp are the usual four. Check node_modules/**/package.json for libc fields before assuming a clean install means a working image.

2. glibc binaries fail with a misleading error

A binary linked against glibc produces sh: ./app: not found on Alpine, not GLIBC_2.34 not found, because the interpreter /lib64/ld-linux-x86-64.so.2 is missing. ldd ./app on the Debian side names the missing libraries; apk add libc6-compat fixes only a small subset and cannot bridge newer symbol versions.

bash
docker run --rm --entrypoint sh myimage -c 'ls -l /lib64/ld-linux-x86-64.so.2'

If that path is absent, the image cannot run that binary, and no apk add will change it.

3. The five-second DNS delay in Kubernetes

musl sends A and AAAA queries and walks the search list serially, while glibc parallelises and caches. In a pod with ndots:5, api.stripe.com is first tried as api.stripe.com.<ns>.svc.cluster.local and so on, each attempt consuming a timeout.

yaml
spec: dnsConfig: options: - name: ndots value: "1"

Setting ndots:1 on the pod removes the search expansion for names that already contain a dot, which is most outbound API calls. A second lever is options single-request-reopen for UDP socket reuse, and a NodeLocal DNSCache removes the per-pod query entirely.

4. Timezone and locale data are not included

Alpine ships neither tzdata nor locales, so TZ=Asia/Seoul is ignored and strftime("%Z") returns UTC.

dockerfile
RUN apk add --no-cache tzdata && cp /usr/share/zoneinfo/Asia/Seoul /etc/localtime ENV TZ=Asia/Seoul

Python's zoneinfo needs tzdata from PyPI on Alpine as well, because the system package is the usual source of the database.

5. Static linking as an honest alternative

A Go or Rust binary compiled with CGO_ENABLED=0 or --target x86_64-unknown-linux-musl has no libc dependency, and then Alpine's size advantage is real rather than a hidden risk.

dockerfile
FROM golang:1.23-alpine AS build ENV CGO_ENABLED=0 RUN go build -ldflags="-s -w" -o /app ./cmd/server FROM scratch COPY --from=build /app /app ENTRYPOINT ["/app"]

A FROM scratch image is smaller than Alpine and has no resolver of its own; Go's pure resolver handles DNS in userspace, which sidesteps the musl behaviour entirely.

6. Multi-stage build and cache reuse

Whatever the base, keep the toolchain out of the runtime layer:

dockerfile
FROM node:22-trixie-slim AS deps WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev FROM node:22-trixie-slim WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . USER node CMD ["node", "server.js"]

Copying package*.json before the source is what keeps the dependency layer cached across code changes.

Common Compilation/Runtime Mistakes & Version Gotchas

  • apk add in the final stage. Adds ~200 MB of toolchain to the shipped image; build in one stage, copy artifacts.
  • python:3.x-alpine with cryptography or psycopg[binary]. No musllinux wheel for every version and platform; expect a compiler.
  • pip install --no-binary :all: copied from a tutorial. Forces source builds that Alpine cannot complete without headers.
  • node:alpine for a Next.js standalone image. sharp and font rendering both need attention; bookworm-slim is the smaller risk.
  • ndots left at the cluster default. Every external hostname pays the search list, and the delay is invisible in application logs.
  • libc6-compat treated as a glibc substitute. It is a shim for a handful of symbols, not a libc.
  • Alpine's OpenSSL switch in 3.9. Images pinned to 3.8 and older linked LibreSSL; a package upgrade changes the runtime ABI.

Related tools. Inspect the JSON your health endpoint returns from inside the container with the JSON formatter, diff two Dockerfiles before and after a base-image change with the text diff, and decode the base64 payload of a failing getaddrinfo trace with the Base64 decoder.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.