What does a wheel repair step such as auditwheel or delocate do to a freshly built extension wheel?

## The problem the repair step solves A compiled extension is a shared library that the interpreter loads with the operating system's dynamic loader. When it was linked, the linker recorded the *names* of the other shared libraries it needs — a compression library, a maths library, a codec — but not their contents and not their location. At import time the loader resolves those names against the host: a search path baked into the binary, then the system's configured library directories. On the build machine everything resolves, because those libraries were installed there to compile against. On another host the outcomes are worse and progressively harder to diagnose: the library is absent and the import fails immediately with a loader error naming a missing object; or a differently-versioned copy is present, resolves, and produces wrong results or a crash somewhere far from the import. A team running a metrics scraper on a slim host will see the first shape as a service that will not start at all, which is at least honest. A wheel is supposed to be installable by unpacking it. So a wheel containing an extension has to stop depending on the build machine's library set. That is exactly what a repair step does. ## What the tools actually do Run after the wheel is built, a repair tool performs four operations: 1. **Discover the dynamic dependencies.** It reads the extension binaries in the wheel and lists the shared libraries each one names, then resolves them on the build host to real files. 2. **Classify against a policy.** Libraries considered part of the platform — the C runtime, the maths library, the threading library, core system components — are left alone; everything else is a candidate for bundling. On Linux this policy is what the `manylinux` compatibility profiles describe, and the tool refuses to certify a wheel that depends on something outside the profile. 3. **Vendor and rewrite.** The chosen libraries are copied into a private directory inside the wheel, and the extension's recorded search path is patched so the loader finds the bundled copies rather than searching the host: a run path relative to the binary's own location on Linux, a loader-relative install name on macOS, and on Windows, where there is no run path, the tool injects code so the package's directory is added to the DLL search order before the extension loads. 4. **Mangle names.** Vendored files are renamed with a content hash and the internal name the loader matches on is rewritten to match. This is the step people underestimate. A process has one namespace for loaded shared libraries: if two installed packages each vendor a different version of the same library under the same name, the first one loaded wins for both, and the second package silently runs against a version it was never compiled against. Hash-mangled names make the two files genuinely different libraries, so both are loaded and each package gets its own. The tool then rewrites the wheel's platform tag to the compatibility level it verified, so the archive advertises what it actually requires. ## What repair does not do It does not compile anything, it does not make a wheel work on a different processor architecture or a different interpreter ABI, and it does not turn a badly-configured build into a portable one. If the extension links against something the policy will not let you bundle, the fix is at build time — statically link it, or build in an image whose baseline is old enough. ## The cost of vendoring Bundling is not free, and a senior answer says so. - **Size.** Wheels grow, sometimes by an order of magnitude, and every environment that installs several such packages carries several near-identical copies. - **Memory.** Two packages vendoring the same library load two copies into the process; the deduplication a shared system library would have given you is gone by design. - **Patching becomes yours.** When a vulnerability lands in a library you vendored, no operating system update fixes your users. You must rebuild and re-release every affected wheel, and downstream consumers must upgrade your package. Distribution packagers dislike vendored wheels for exactly this reason and typically rebuild from the sdist against system libraries. - **Global state.** A library with process-wide state — a registry, a plugin table, a signal handler — can genuinely misbehave when two mangled copies are loaded at once. Bundling solves the version conflict but not every conflict. ## Where it fits in the release The repair step belongs immediately after the build and before the wheel is uploaded or tested: build in a controlled image whose system libraries define your baseline, repair the wheel, then install the *repaired* wheel in a clean environment and import it there. Testing the wheel you built rather than the one you repaired is the mistake that ships broken artefacts, because the build machine still has every library the extension needs.