Auditing and Repairing Wheels

Auditing and Repairing Wheels#

When a Python extension links against shared libraries (.so files), those libraries must be available at runtime. On native platforms, auditwheel handles this by copying the shared libraries into the wheel. For WebAssembly wheels, pyodide-build uses auditwheel-emscripten via the pyodide auditwheel command.

Install#

auditwheel-emscripten is included as a dependency of pyodide-build and is available as a pyodide CLI plugin:

pip install pyodide-build
pyodide auditwheel --help

When do you need this?#

If your package links against a shared library that isn’t included in the wheel after running python -m build, you need to vendor that library into the wheel. Otherwise, the .so file will fail to load at runtime with an error like:

ImportError: unable to load shared library 'libfoo.so'

Inspecting a wheel#

Before repairing, inspect the wheel to see what shared libraries it depends on:

pyodide auditwheel show dist/your_package-*.whl

This lists all shared library dependencies of the wheel’s .so files and shows which are already included and which need to be vendored.

Repairing a wheel#

The repair command finds the shared library dependencies and copies them into the wheel:

pyodide auditwheel repair dist/your_package-*.whl --libdir /path/to/libdir

The --libdir option specifies the directory where the shared libraries are located.

By default, the wheel is repaired in place, but you can specify an output directory with -o:

pyodide auditwheel repair dist/your_package-*.whl -o repaired/

The repair process:

  1. Scans all .so files in the wheel for shared library dependencies

  2. Locates the required libraries in the specified --libdir

  3. Copies them into a <package>.libs/ directory inside the wheel

  4. Updates the RPATH of the .so files to point to the vendored libraries

Typical workflow#

# 1. Build the wheel
pyodide build .

# 2. Inspect shared library dependencies
pyodide auditwheel show dist/your_package-*.whl

# 3. Vendor shared libraries into the wheel
pyodide auditwheel repair dist/your_package-*.whl --libdir /path/to/libdir

# 4. Test the repaired wheel
pyodide venv .venv-pyodide
source .venv-pyodide/bin/activate
pip install dist/your_package-*.whl
python -m pytest tests/

In cibuildwheel#

Unlike manylinux, cibuildwheel doesn’t automatically run auditwheel repair for Pyodide. This is because we don’t know where to locate the shared libraries that the .so files depend on. We cannot find them from the host system paths since we need cross-compiled libraries not the host’s libraries.

Therefore, you need to set the libdir explicitly in the cibuildwheel configuration.

[tool.cibuildwheel.pyodide]
repair-wheel-command = "pyodide auditwheel repair --libdir /path/to/libraries --output-dir {dest_dir} {wheel}"

What’s next?#