auditwheel
Auditing and relabeling of PEP 600 manylinux_x_y, PEP 513 manylinux1, PEP 571 manylinux2010 and PEP 599 manylinux2014 Linux wheels.
Overview
auditwheel
is a command line tool to facilitate the creation of Python
wheel packages for Linux (containing pre-compiled
binary extensions) that are compatible with a wide variety of Linux distributions,
consistent with the PEP 600 manylinux_x_y, PEP 513 manylinux1, PEP 571 manylinux2010 and PEP 599 manylinux2014 platform tags.
auditwheel show
: shows external shared libraries that the wheel depends on
(beyond the libraries included in the manylinux
policies), and
checks the extension modules for the use of versioned symbols that exceed
the manylinux
ABI.
auditwheel repair
: copies these external shared libraries into the wheel itself,
and automatically modifies the appropriate RPATH
entries such that these libraries
will be picked up at runtime. This accomplishes a similar result as if the libraries had
been statically linked without requiring changes to the build system. Packagers are
advised that bundling, like static linking, may implicate copyright concerns.
Installation
auditwheel
can be installed using pip:
$ pip3 install auditwheel
It requires Python 3.6+, and runs on Linux. It requires that the shell command
unzip
be available in the PATH
. Only systems that use ELF-based linkage
are supported (this should be essentially every Linux).
In general, building manylinux1
wheels requires running on a CentOS5
machine, building manylinux2010
wheels requires running on a CentOS6
machine, and building manylinux2014
wheels requires running on a CentOS7
machine, so we recommend using the pre-built manylinux Docker images, e.g.
$ docker run -i -t -v `pwd`:/io quay.io/pypa/manylinux1_x86_64 /bin/bash
Examples
Inspecting a wheel:
$ auditwheel show cffi-1.5.0-cp35-cp35m-linux_x86_64.whl cffi-1.5.0-cp35-cp35m-linux_x86_64.whl is consistent with the following platform tag: "linux_x86_64". The wheel references the following external versioned symbols in system-provided shared libraries: GLIBC_2.3. The following external shared libraries are required by the wheel: { "libc.so.6": "/lib64/libc-2.5.so", "libffi.so.5": "/usr/lib64/libffi.so.5.0.6", "libpthread.so.0": "/lib64/libpthread-2.5.so" } In order to achieve the tag platform tag "manylinux1_x86_64" the following shared library dependencies will need to be eliminated: libffi.so.5
Repairing a wheel.
$ auditwheel repair cffi-1.5.2-cp35-cp35m-linux_x86_64.whl Repairing cffi-1.5.2-cp35-cp35m-linux_x86_64.whl Grafting: /usr/lib64/libffi.so.5.0.6 Setting RPATH: _cffi_backend.cpython-35m-x86_64-linux-gnu.so to "$ORIGIN/.libs_cffi_backend" Previous filename tags: linux_x86_64 New filename tags: manylinux1_x86_64 Previous WHEEL info tags: cp35-cp35m-linux_x86_64 New WHEEL info tags: cp35-cp35m-manylinux1_x86_64 Fixed-up wheel written to /wheelhouse/cffi-1.5.2-cp35-cp35m-manylinux1_x86_64.whl
Limitations
auditwheel
uses the DT_NEEDED information (likeldd
) from the Python extension modules to determine which system libraries they depend on. Code that dynamically loads libraries at runtime usingctypes
/cffi
(from Python) ordlopen
(from C/C++) doesn't contain this information in a way that can be statically determined, so dependencies that are loaded via those mechanisms will be missed.There's nothing we can do about "fixing" binaries if they were compiled and linked against a too-recent version of
libc
orlibstdc++
. These libraries (and some others) use symbol versioning for backward compatibility. In general, this means that code that was compiled against an old version ofglibc
will run fine on systems with a newer version ofglibc
, but code what was compiled on a new system won't / might not run on older system.So, to compile widely-compatible binaries, you're best off doing the build on an old Linux distribution, such as a manylinux Docker image.
Testing
The tests can be run with tox
, which will automatically install
test dependencies.
Some of the integration tests also require a running and accessible Docker daemon. These tests will pull a number of docker images if they are not already available on your system, but it won't update existing images. To update these images manually, run:
docker pull python:3.6-slim docker pull quay.io/pypa/manylinux1_x86_64 docker pull quay.io/pypa/manylinux2010_x86_64 docker pull quay.io/pypa/manylinux2014_x86_64 docker pull quay.io/pypa/manylinux_2_24_x86_64
You may also remove these images using docker rmi
.
Code of Conduct
Everyone interacting in the auditwheel
project's codebases, issue trackers,
chat rooms, and mailing lists is expected to follow the
PSF Code of Conduct.