Python Builds and Compatible Package Wheels

Published . Nil revisions.

Wheels

Wheels (.whl) are type of built distribution format used to distribute Python packages. A built distribution contains files and metadata that only needs to be moved to the correct directory to be installed on a system. This does not imply that files have to be pre-compiled (Wheels intentionally do not include pre-compiled files).

The wheels available for a particular package can be found on the associated Python Package Index (PyPI) project web-page under the "Built Distributions" subsection of the "Download files" section (as an example, see the built distributions listed for the TensorFlow project).

Compatibility Tags

Each wheel will have a compatibility tag which lists the Python version, Application Binary Interface (ABI) and platform (operating system and architecture) for which the package is compatible. The general format is <pythontag>-<abitag>-<platformtag>.

Python Tag

The Python tag lists the Python implementation and version that is compatible with the wheel. Major implementations and their character codes include:

  • cp: CPython
  • py: Generic Python (does not require implementation-specific features)
  • ip: IronPython
  • pp: PyPy
  • jy: Jython

The implementation characters codes are then succeeded by numerical characters representing the Python version. For example, the cp39 Python tag means that the wheel requires CPython version 3.9.

ABI Tag

The ABI tag specifies the Python implementation and version along with the "extensions" it must support. The three "extensions" include the Python memory allocator (pymalloc), debugging (pydebug) and wide-unicode (wide-unicode): each of which is denoted by the following suffixes. The suffixed letters determine which of these "extensions" had to be included when building Python (i.e. which flags had to be set prior to compilation) (in any combination):

  • m: requires --with-pymalloc to be set when building.
    • As of Python 3.8, whether Python was compiled with-pymalloc or not has no impact on the ABI. Hence, the m ABI flag is no longer required for packages targeting Python versions 3.8 or later.
  • d: requires --with-pydebug to be set when building.
    • As of Python 3.8, the incompatibility of Python debug builds with packages compiled for non-debug builds was removed. Hence, package installation issues may arise if using a debug Python version prior to 3.8 and attempting to install wheels without the d suffix.
  • u: requires --with-wide-unicode to be set when building.
    • As of Python 3.3, which implements PEP 393, "wide-unicode" is no longer required as flexible 1, 2 or 4 bytes character representations are used instead of the hard-coded 2 or 4 bytes per character which would be determined at the time Python was built via the --with-wide-unicode flag.

Platform Tag

The platform tag specifies the operating system and the architecture that is compatible with the wheel. The common operating systems include:

  • win for Windows
  • manylinux for Linux
  • macosx for Mac OS X

For manylinux, the tag is further specified by what version of Linux the package is expected to run on, or more concretely, that the modules in the package only link against a small set of system-level share libraries. The manylinux standard has progressed significantly over the last decade, more information can be found on the manylinux GitHub repository. Note that only certain versions of pip support particular manylinux standards as detailed in the following table:

pip version manylinux standard
>=8.1.0 manylinux1 (PEP 513)
>=19.0 manylinux2010 (PEP 571)
>=19.3 manylinux2014 (PEP 599)
>=20.3 manylinux_x_y (PEP 600)

The most recent standard, manylinux_x_y, refers to the glibc major (x) and minor (y) version that should be available on the system. To determine the system's glibc version: 

ldd --version

glibc is backwards compatible, so as long as one selects a wheel that is equal to or below the glibc version, it will install.

The final part of the platform tag is the architecture upon which the package is intended to be used. Some examples of architectures include:

  • x86_64: 64bit x86 instruction set
  • aarch64: 64bit A64 instruction set
  • arm7l: 32bit RISC on ARMv7 CPUs

To determine the current system architecture:

python -c "import sysconfig; print(sysconfig.get_platform())"

If a package fails to install because no compatible wheels were available. Use the following command to view the all wheels for a particular package to be installed along with their compatibility tags: 

pip install -vvv <package-name>

To view the list of compatible tags for the current Python environment:

pip debug --verbose