Python "ld: cannot find -lz" Linking a C Extension in CI

Compilation succeeded but linking failed: the linker was told to link -lz (zlib) and could not find the library. The runtime library may exist, but the -dev package that provides the linkable .so symlink is missing.

What this error means

A source build reaches the link step and fails with /usr/bin/ld: cannot find -lz (or -lssl, -ljpeg, -lxml2). The compiler ran fine; only linking against the named system library failed.

gcc -shared build/temp.../foo.o -L/usr/lib -lz -o build/lib.../foo.so
/usr/bin/ld: cannot find -lz: No such file or directory
collect2: error: ld returned 1 exit status

Common causes

The library’s dev package is missing

The linker needs the -dev package (e.g. zlib1g-dev for -lz) which provides the libz.so symlink and headers. The runtime .so.1 alone is not linkable.

No prebuilt wheel for the platform

With no compatible wheel, pip builds from source and must link the system library, exposing the missing dev package.

How to fix it

Install the matching dev package

Map the missing -l<name> to its dev package and install it.

# -lz -> zlib1g-dev ; -lssl -> libssl-dev ; -ljpeg -> libjpeg-dev
apt-get update && apt-get install -y zlib1g-dev

Prefer a wheel to skip linking

pip install --only-binary :all: <package>

How to prevent it

• Bake required -dev packages into images that build native extensions.
• Map each -l<name> link error to its -dev package and install it.
• Prefer wheels in CI so the linker step is skipped.

Related guides