Skip to main content

Cross-distribution Linux wheels

Project description

https://travis-ci.org/pypa/auditwheel.svg?branch=main https://badge.fury.io/py/auditwheel.svg https://pepy.tech/badge/auditwheel/month

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.

Requirements

  • OS: Linux

  • Python: 3.9+

  • patchelf: 0.14+

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

Installation

auditwheel can be installed using pip:

$ pip3 install auditwheel

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

  1. auditwheel uses the DT_NEEDED information (like ldd) from the Python extension modules to determine which system libraries they depend on. Code that dynamically loads libraries at runtime using ctypes / cffi (from Python) or dlopen (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.

  2. There’s nothing we can do about “fixing” binaries if they were compiled and linked against a too-recent version of libc or libstdc++. These libraries (and some others) use symbol versioning for backward compatibility. In general, this means that code that was compiled against an old version of glibc will run fine on systems with a newer version of glibc, 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 nox, 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.9-slim-bookworm
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_28_x86_64
docker pull quay.io/pypa/manylinux_2_34_x86_64
docker pull quay.io/pypa/musllinux_1_2_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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

auditwheel-6.4.0.tar.gz (5.1 MB view details)

Uploaded Source

Built Distribution

auditwheel-6.4.0-py3-none-any.whl (50.8 kB view details)

Uploaded Python 3

File details

Details for the file auditwheel-6.4.0.tar.gz.

File metadata

  • Download URL: auditwheel-6.4.0.tar.gz
  • Upload date:
  • Size: 5.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for auditwheel-6.4.0.tar.gz
Algorithm Hash digest
SHA256 20990ccb2416fdb81983ef654d10df72f9f25b388e30105bc3d97b06d6aecafb
MD5 93a1ad28c7147bca70af1b77c4ddf679
BLAKE2b-256 fbf3b61e3b5ccceee2c25baff6c16146d031f6f5c75b1c09d598bfbfe498adec

See more details on using hashes here.

File details

Details for the file auditwheel-6.4.0-py3-none-any.whl.

File metadata

  • Download URL: auditwheel-6.4.0-py3-none-any.whl
  • Upload date:
  • Size: 50.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for auditwheel-6.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c97d286ecd8c43c998ca7c312d3ba1773327349f732faf2a77b8b9fea4f48696
MD5 be8e07b4f8cb25cbf6babf24fb1d6cf8
BLAKE2b-256 fc568f4ebf2e90c093530859cfb4f5f7ee3b13521248c092b76f220286dce385

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page