Python Wheel Filename Tags Explained

Python wheel filenames use standardized compatibility tags to ensure package installers like pip download binary packages that match your specific system environment. In a tag triplet such as cp311-cp311-manylinux_2_17_x86_64, the filename encodes the Python implementation and version, the Application Binary Interface (ABI), and the target operating system and CPU architecture. This guide breaks down each component of this compatibility tag triplet to explain exactly what it means and how it works.

The Compatibility Tag Triplet Structure

A wheel's compatibility is defined by a triplet format: {python tag}-{abi tag}-{platform tag}. These components tell package installers whether a pre-compiled binary can run on the target machine without requiring a source build.

1. The Python Tag: cp311

The first segment indicates the Python implementation and the language version the wheel was built for:

• cp: Identifies the Python implementation. Here, cp stands for CPython, the standard reference implementation of Python written in C. Other examples include pp for PyPy or py for pure Python code independent of the implementation.
• 311: Denotes the version number. In this case, it indicates Python version 3.11. A wheel marked py3 or py2.py3 would signify generic Python 3 or universal Python 2/3 compatibility.

2. The ABI Tag: cp311

The middle segment defines the Application Binary Interface (ABI) requirements:

• cp311: Specifies that the compiled C extensions within the wheel rely on the specific CPython 3.11 ABI. Because CPython's internal C API can change between minor releases, compiled extensions must match the runtime's ABI.
• Alternative tags: Pure Python wheels typically use none because they contain no compiled binary extensions. Wheels built using Python's Stable ABI (PEP 384) use tags like abi3, allowing a single binary wheel to run across multiple Python versions (e.g., Python 3.8 and newer).

3. The Platform Tag: manylinux_2_17_x86_64

The final segment identifies the operating system, system libraries, and CPU architecture required to run the binary:

• manylinux_2_17: Specifies compliance with the Linux binary compatibility standard defined in PEP 599. It guarantees that the wheel only depends on common system libraries and an older version of the GNU C Library (glibc 2.17 or higher). This ensures the compiled binary can execute reliably across diverse Linux distributions, such as Debian, Ubuntu, CentOS, and Fedora, rather than being tied to a single distribution.
• x86_64: Specifies the hardware architecture. Here, it indicates 64-bit x86 processors (AMD64 / Intel 64). Other common architectures include aarch64 (64-bit ARM) or armv7l.

How Installers Use This Information

When you run pip install, the installer checks your machine's Python version, ABI, operating system, and hardware architecture. It compares your system against the compatibility tags present on available wheels in the index. If a wheel's triplet satisfies all three parameters—CPython 3.11, matching ABI, and an x86_64 Linux system with glibc 2.17 or newer—pip downloads and unpacks the binary, bypassing the need to compile code locally.