Python Sdist vs Wheel: Architectural Differences

Python packages are distributed primarily in two formats: Source Distributions (sdists) and Built Distributions (wheels). While both deliver reusable code to end-users via package managers like pip, their underlying architectures serve fundamentally different stages of the software deployment lifecycle. An sdist contains raw, uncompiled source code and build instructions that require the target system to assemble the package, whereas a wheel is a pre-built, ready-to-unpack archive designed to be installed directly into Python's site-packages directory without a local compilation step.

The Source Distribution (sdist) Architecture

A Source Distribution, typically packaged as a .tar.gz archive, mirrors the developer's source repository rather than the final runtime environment.

Architecturally, an sdist contains:

• Raw Source Code: Pure Python modules, packages, and uncompiled source files for extensions written in languages like C, C++, or Rust.
• Build Definitions: Files such as pyproject.toml, setup.py, or setup.cfg that declare how the project must be compiled and packaged.
• Source Metadata: The PKG-INFO file containing project metadata generated when the distribution was created.

When a client installs an sdist, the build execution is deferred to the consumer's machine. The package installer must create an isolated build environment, install necessary build dependencies (such as setuptools, flit, or maturin), invoke the build backend to compile any C/C++ extensions, and generate a temporary wheel on the fly before installation can finish.

The Built Wheel (wheel) Architecture

Standardized under PEP 427, a wheel is a built distribution packaged as a .whl file, which is internally a standard ZIP archive.

A wheel is architecturally mapped to match the target filesystem layout of a Python installation. It contains:

• Ready-to-Execute Code: Pre-arranged Python modules and bytecode, as well as compiled binary shared libraries (.so on Linux, .pyd on Windows, .dylib on macOS) matching specific CPU architectures and Python ABIs.
• The .dist-info Directory: A standardized metadata directory containing runtime metadata (METADATA), entry point configurations (entry_points.txt), license data, and a cryptographic manifest (RECORD) listing every file in the archive along with its hash and size.
• Optional .data Directory: Subdirectories designed to install files directly into system paths, such as headers, scripts, or documentation.

Installing a wheel requires no build tools. The installer simply unpacks the archive directly into site-packages and updates metadata records, turning installation into a rapid, atomic file-copy operation.

Key Architectural Differences

Execution Location of the Build Phase

In an sdist workflow, the compilation and packaging pipeline executes on the end-user's host. This requires the host to maintain compatible C/C++ compilers, system development headers, and platform libraries. In a wheel workflow, the build phase is executed upstream by the package maintainer or CI/CD pipeline, decoupling the target environment from compilation toolchains.

Portability and Platform Tagging

Because an sdist is pure source, it is inherently platform-agnostic, though it may fail to compile if target system dependencies are missing. Wheels, by contrast, use strict platform compatibility tagging embedded directly in their filenames (e.g., package-1.0.0-cp311-cp311-manylinux_2_17_x86_64.whl). These tags enforce compatibility across the Python implementation, ABI version, OS, and hardware architecture. Pure Python wheels are tagged generically (e.g., py3-none-any.whl).

Installation Determinism and Security

Sdist installations historically relied on running arbitrary code at install time (such as setup.py install). While modern build systems isolate this step via standardized hooks, installing from an sdist can still introduce non-deterministic behavior based on local system libraries. Wheels are completely static; they contain no executable installation scripts, eliminating arbitrary code execution during the installation phase and guaranteeing identical file layouts across deployments.