auditwheel "cannot be located" / patchelf shared library in CI

During auditwheel repair, the tool resolves every external shared library the extension links and copies it into the wheel using patchelf. If a required .so is not on the loader path, or patchelf is not installed, the repair fails.

What this error means

auditwheel repair fails saying a library "cannot be located" (for example libfoo.so.1), or it errors that patchelf is not installed or too old.

auditwheel: error: cannot repair "mypkg.whl" to "manylinux_2_28_x86_64":
ValueError: Cannot repair wheel, because required library "libfoo.so.1" could not be located

Common causes

A linked .so is not on the library path

auditwheel can only bundle libraries it can find. If the dependency is not on LD_LIBRARY_PATH or installed, it cannot be located.

patchelf missing or outdated

auditwheel uses patchelf to rewrite RPATHs; without a recent patchelf the repair cannot proceed.

How to fix it

Install the library and patchelf, then repair

1. Install the system package that provides the missing .so.
2. Add its directory to LD_LIBRARY_PATH.
3. Ensure patchelf is present, then run repair.

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
pip install patchelf
auditwheel repair dist/*.whl -w wheelhouse/

Build inside the manylinux image

manylinux images ship patchelf and a known toolchain; building there avoids missing-tool failures.

env:
  CIBW_MANYLINUX_X86_64_IMAGE: "manylinux_2_28"

How to prevent it

• Make every linked library discoverable before repair.
• Run auditwheel inside the official manylinux images.
• Keep patchelf installed and current in the build env.

Related guides