"version `GLIBC_2.xx' not found" and how to diagnose a glibc mismatch

What it is

The full line reads like ./app: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.32' not found (required by ./app). It is printed by the dynamic linker (invoked implicitly when an ELF executable starts, or explicitly through ldd) when the binary references a versioned symbol, such as GLIBC_2.32, that the libc.so.6 present on the running system does not provide. It means the binary was built against, or explicitly requires, a newer glibc than the one installed where it is being run; glibc's own symbol versioning is backward compatible (a newer glibc runs binaries built for older ones) but not forward compatible (an older glibc cannot satisfy a binary that names a version it never shipped).

Why it matters

This surfaces constantly when a binary is built in one container image (a recent Linux distribution with a current glibc) and then copied into or run against an older base image, or when a prebuilt binary or Python wheel downloaded from the internet was built on a newer distribution than the target host or CI runner.

How to apply

• Diagnose: ldd --version (documented by the ldd(1) manual page) reports the glibc version the current system runs. ldd ./binary lists which shared objects and versions are missing, but the manual page warns that ldd may execute the program, so never run it on an untrusted binary; use objdump/readelf there. objdump -T ./binary | grep GLIBC_2 (GNU Binutils' objdump) or readelf --dyn-syms ./binary (readelf) shows the highest GLIBC_2.x version the binary actually requires; compare it against objdump -T /lib/x86_64-linux-gnu/libc.so.6 | grep GLIBC_2 on the target system to see what is actually available.
• Fixes, least to most invasive:
  1. Run the binary on, or inside a container based on, a distribution whose glibc is at least as new as required — match the build environment to the oldest system you must support, not the newest one available to the builder.
  2. Build on an older baseline distribution deliberately, since a binary built there will still run on newer systems.
  3. Link statically, or build against musl instead of glibc (for example inside Alpine), removing the runtime glibc dependency; see the separate article on musl-versus-glibc trade-offs for what that changes.
  4. Ship the binary together with a container image whose glibc matches the build environment, so build and run always agree.
• Unsafe: manually copying a newer libc.so.6 onto an older system. glibc is not designed to be swapped independently of the dynamic loader and other core libraries, and doing so can break every other program on that system.

Pitfalls

• Assuming a "GLIBC not found" error means glibc is missing entirely; it is present but too old.
• Confusing this with a musl-linked binary started on a glibc system (or the reverse): that usually fails with No such file or directory because the binary's dynamic loader path does not exist, which has a different fix.