Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

Wheels, Sdists and the Package Index

Decode wheel filenames and compatibility tags, understand why wheels install faster than sdists, and see how PyPI and the simple index serve both formats.

Look in the "Download files" tab of any project on PyPI and you will find names like numpy-2.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl. That string is not noise. It is a compact contract between the file and the installer: "I work on this Python, this ABI and this platform." Learning to read it explains many installation surprises, such as why one machine downloads in a second and another spends minutes compiling.

Two kinds of distribution

A source distribution (sdist) is a .tar.gz of your project's source plus metadata (PKG-INFO) and, normally, pyproject.toml. To install it, the installer must first build it: run the project's build backend, which may call a C compiler. A wheel is a .whl file (really a zip) that is already built. Installing it is little more than unpacking.

Wheel Sdist
Extension .whl .tar.gz
Contains Ready-to-use files + .dist-info Source tree + PKG-INFO
Install cost Copy files Build first (may compile)
Runs project code at install? No Yes (the build backend)
Tied to a platform? Maybe (compiled), or any No

Because wheels never execute arbitrary build scripts at install time, they are also safer and more reproducible. Ship both: wheels for speed, an sdist so that distributions can rebuild from source.

Reading a wheel filename

The format (PEP 427) is:

TEXT
{distribution}-{version}(-{build})?-{python tag}-{abi tag}-{platform tag}.whl

The three compatibility tags say where the wheel runs:

  • Python tag: py3 (any Python 3), cp312 (CPython 3.12), py2.py3.
  • ABI tag: none (no compiled code that cares), abi3 (stable ABI, one wheel for many versions), cp312 (that exact build).
  • Platform tag: any, win_amd64, macosx_11_0_arm64, manylinux_2_28_x86_64, musllinux_1_2_aarch64.

A pure-Python project usually ships exactly one wheel, py3-none-any. A project with C extensions ships many.

Python Parsing wheel filenames into tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that parse_wheel_filename normalizes the name: pydantic_core becomes pydantic-core. PyPI treats -, _ and . as equal and case-insensitive (PEP 503 normalization), so Pydantic_Core and pydantic-core are the same project.

What the installer checks

When pip sees a list of files for one release, it asks "which of these tags does my interpreter support?" and picks the best match. You can list your own supported tags, ordered from most to least specific.

Python Which tags does this interpreter accept?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In the browser the interpreter is WebAssembly (emscripten/pyodide platform), so only wheels tagged any or built for it match. That is why many compiled packages cannot be installed with micropip, while pure-Python ones can. A normal desktop pip shows a long list of manylinux, cp3xx and abi3 tags instead.

manylinux and musllinux

Linux distributions differ in their system C library. To avoid thousands of one-off builds, wheels follow the manylinux standard: they are built against an old, common glibc (named by its version, for example manylinux_2_28) and run on any newer distribution. Alpine Linux uses a different library, musl, so it needs musllinux wheels. If a compiled package has no wheel for your platform, pip falls back to the sdist and needs a compiler. That fallback is the usual reason a Docker build on Alpine becomes slow.

The package index

An index is a web service listing files per project. The core protocol is the simple repository API (PEP 503 for HTML, PEP 691 for JSON), deliberately minimal: GET /simple/<project>/ returns links to every file, with hashes and requires-python hints. PyPI is the default, but you can run your own (devpi, a private artifact server, a cloud registry), or use --index-url and --extra-index-url.

flowchart LR
    P["pip install demo"] --> I["GET /simple/demo/"]
    I --> L["List of files<br/>(wheels + sdist, hashes)"]
    L --> T{"Any wheel<br/>matches my tags?"}
    T -- yes --> W["Download wheel<br/>unpack"]
    T -- no --> S["Download sdist<br/>build a wheel locally<br/>then install"]

The installer prefers a matching wheel and falls back to building the sdist.

Python Normalizing names the way an index does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

If pip install is compiling something and you did not expect it, run it again with --only-binary :all:. It will fail loudly and tell you which package has no wheel for your platform.

Hashes and trust

Index listings include SHA-256 hashes for each file. With pip install --require-hashes -r requirements.txt pip refuses any file whose hash is not listed, which protects against tampering and surprise releases. Lock files from uv, poetry and pip-tools --generate-hashes store hashes for exactly this reason. You will build the hash records yourself in Building an sdist and a Wheel.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the wheel tag py3-none-any mean?

    py3 = any Python 3, none = no ABI dependency, any = any platform: a pure-Python wheel.
  2. 2. Why can installing an sdist be slower and riskier than installing a wheel?

    A wheel is unpacked; an sdist triggers a build step that executes code and may need a compiler.
  3. 3. On PyPI, how are the names Typing_Extensions and typing-extensions related?

    PEP 503 normalization lowercases and collapses runs of -, _ and . into a single hyphen.
  4. 4. Why does a compiled package sometimes build from source on Alpine Linux?

    manylinux wheels target glibc. Without a musllinux wheel, pip falls back to the sdist.

Summary

  • A wheel is a built zip ready to unpack; an sdist is source that must be built on install.
  • Wheel filenames encode name-version-pythontag-abitag-platformtag.
  • Installers choose the most specific wheel whose tags match the interpreter, else build the sdist.
  • manylinux and musllinux wheels target different Linux C libraries.
  • Indexes expose files and hashes through the simple API; project names are normalized.
  • Hash-checking installs protect against tampering.

Next: The Python Tooling Landscape