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.

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.
# 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')# 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 /wheels /wheels
RUN pip install --no-cache-dir --no-index --find-links /wheels /wheels/*.whlReproduce the DNS delay without Kubernetes: run a container on a network with a search domain and time one lookup.
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
| Aspect | Alpine | Debian slim |
|---|---|---|
| libc | musl | glibc |
| Base image size | ~7 MB | ~75 MB |
manylinux wheels | rejected | installed |
| Python native builds | need build-base | usually prebuilt |
| Node native modules | linux-x64-musl needed | linux-x64-gnu |
| CVE surface | smaller package set | more packages to patch |
getent hosts with ndots:5 | slow, serial | parallel, cached |
| Shell | busybox ash | dash / bash |
| Failure | Message | Resolution |
|---|---|---|
| Missing toolchain | gcc: No such file or directory | apk add build-base in a builder stage |
| glibc binary on musl | no such file or directory though the file exists | rebuild against musl, or use slim |
| Node prebuild mismatch | Could not load the "sharp" module | install with --libc=musl or drop Alpine |
| DNS slowness | 5s per new hostname | ndots:1, or single-request-reopen |
| Missing zoneinfo | TZ has no effect | apk add tzdata |
ld-linux-x86-64.so.2 | not found at exec | the 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.
# 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-slimbcrypt, 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.
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.
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.
RUN apk add --no-cache tzdata && cp /usr/share/zoneinfo/Asia/Seoul /etc/localtime
ENV TZ=Asia/SeoulPython'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.
FROM golang:1.23-alpine AS build
ENV CGO_ENABLED=0
RUN go build -ldflags="-s -w" -o /app ./cmd/server
FROM scratch
COPY /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:
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 /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 addin the final stage. Adds ~200 MB of toolchain to the shipped image; build in one stage, copy artifacts.python:3.x-alpinewithcryptographyorpsycopg[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:alpinefor a Next.js standalone image.sharpand font rendering both need attention;bookworm-slimis the smaller risk.ndotsleft at the cluster default. Every external hostname pays the search list, and the delay is invisible in application logs.libc6-compattreated 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 toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker Compose Connection Refused: localhost vs Service DNS
localhost inside a container is that container. Compose resolves service names on a shared network, depends_on does not wait for readiness, and binding loopback breaks the rest.
Docker BuildKit failed to solve: Exit Codes, Build Context, and Network
BuildKit puts every failure under one prefix. The exit code after did not complete successfully is the whole diagnosis: 100 is apt, 127 is a missing binary, and cache key is a file outside the context.
Docker Inspect: Go Templates, Format Flags, and JSON Filtering
The fields worth knowing, the array-versus-object trap, and why <no value> silently passes your monitoring check instead of failing it.
Docker Restart Policies: no, on-failure, always, and unless-stopped
What each policy really restarts, why on-failure ignores a clean exit, how backoff hides crash loops, and why health checks never trigger a restart.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.