What is the difference between a Python sdist (.tar.gz) and a wheel (.whl)?

### Two artefacts, one distinction A Python project can publish exactly two kinds of artefact, and almost everything people find confusing about installing Python code follows from the difference between them: one is **source that must be built**, the other is **a build result that is merely copied into place**. ### The sdist A source distribution is a gzipped tar archive — `name-version.tar.gz` — containing the project's source tree as the author chose to ship it, plus a generated `PKG-INFO` file carrying the core metadata (name, version, requirements, summary). Because it is source, *installing it is a build*. The installer unpacks the tarball into a temporary directory, reads the build-system table in `pyproject.toml` to learn which build backend to use and which packages that backend needs, provisions those in a build environment, and asks the backend to produce a wheel. Only then does it install the wheel it just built. That build has to succeed on **your** machine. For a pure-Python project it usually does: the backend copies files and writes metadata. For a project with C, C++, Rust or Fortran in it, the build needs a matching compiler toolchain, the interpreter's development headers, and the headers and libraries of whatever it links against. This is why an install that normally takes two seconds can take four minutes, and why it can fail on a slim container image with a compiler error that mentions no Python at all. ### The wheel A wheel is a zip file named `name-version[-build]-interpreter-abi-platform.whl`. Inside is a layout defined by the wheel specification: the importable package directories laid out exactly as they should appear in `site-packages`, and a `.dist-info` directory holding the metadata file, a record listing every installed path with its hash and size, a wheel-format marker naming the generator and whether the payload is pure Python, licence files, and the entry-points declaration used to create console scripts. Installing a wheel is a data operation: verify the archive, unpack the payload into the right site-packages root, generate the console-script wrappers described by the entry-points declaration, and write the record file that makes the distribution discoverable to `importlib.metadata` afterwards. **No build backend runs and no project build code executes at install time.** That is the entire point of the format. ### Compatibility lives in the filename Because a wheel is pre-built, it is only valid where its build assumptions hold, and the filename says where. A pure-Python project ships a single `py3-none-any` wheel that installs on every interpreter and platform. A project with compiled code ships one wheel per interpreter/ABI/platform combination it supports, so the same release may carry a dozen files. The installer computes the set of tags its own environment supports, ranks the available wheels against that set, and picks the best match; if nothing matches it downloads the sdist and builds. ### Why wheels exist at all Historically, installing a Python package meant downloading source and executing the project's build script as whatever user ran the installer. Every install was a build, so every install was slow, needed a toolchain, could run arbitrary code, and could produce a subtly different result on each machine. Wheels move that build to the publisher's machine, where it happens once, is reproducible, and can be inspected before it is uploaded. The install side then becomes a predictable unzip. ### Where the sdist still earns its place The sdist is the fallback and the source of record. It covers interpreters and architectures the publisher never built for — a brand-new Python release, an unusual CPU, a platform with no published wheel. It is what distribution packagers and rebuild pipelines consume, because they must build everything from source themselves. It is what an auditor reads and what you patch when you need a one-line fix in a dependency. And it usually contains material the wheel does not: the test suite, build scripts and configuration are build inputs, not install outputs, so they typically ship in the sdist and are stripped from the wheel. ### What this buys you in practice Knowing which artefact you are installing explains three everyday symptoms. An install that suddenly compiles for minutes is a wheel-tag miss falling through to the sdist. A `no matching distribution` error usually means neither a compatible wheel nor a usable sdist exists for your interpreter or platform. And a dependency that installs cleanly on a developer laptop but fails in a minimal CI image is almost always a source build hitting a missing compiler or missing headers — a build-environment problem, not a Python one.