Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 38 ยท Building and Publishing

Building an sdist and a Wheel

Run python -m build, inspect wheel and sdist contents, and create a real wheel by hand with zipfile, RECORD hashes and dist-info, then install it live.

You have a source tree and a pyproject.toml. The next step is turning them into the two artifacts every index understands: a wheel and an sdist. With a configured project this takes one command. Underneath, it is simple file packing with a strict layout, and the best way to understand it is to do it by hand once. This lesson shows the real commands (read-only here) and then builds and installs a genuine wheel in your browser with zipfile.

The one-command build

Terminal
python -m pip install build
python -m build                 # builds BOTH sdist and wheel into dist/
python -m build --wheel         # wheel only
python -m build --sdist         # sdist only
# or with uv:
uv build
TEXT
dist/
  weather_cli-0.3.0.tar.gz              <- sdist
  weather_cli-0.3.0-py3-none-any.whl    <- wheel

build is a frontend: it creates an isolated environment, installs your [build-system].requires, and calls your backend's hooks. By default it builds the sdist first, then builds the wheel from that sdist, which proves that your sdist is complete. pip wheel . and pip install . do the same through pip.

Always rm -rf dist/ build/ before a release build, so that old files do not get uploaded by mistake with twine upload dist/*.

What is inside an sdist

An sdist is a gzip-compressed tar archive with one top-level folder named -{version}:

TEXT
weather_cli-0.3.0/
  PKG-INFO              <- core metadata (same format as METADATA)
  pyproject.toml
  README.md
  LICENSE
  src/weather_cli/...   <- your source files
  tests/...             <- often included, optional

The sdist lets people (and Linux distributions) rebuild from source, run tests and audit the code. Because it carries pyproject.toml, anyone can build a wheel from it with the same backend.

Python Building an sdist by hand with tarfile

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.

Anatomy of a wheel

A wheel is a zip archive with two kinds of top-level content: your files, laid out exactly as they should appear in site-packages, and one metadata directory named -{version}.dist-info.

TEXT
weather_cli-0.3.0-py3-none-any.whl
  weather_cli/__init__.py
  weather_cli/main.py
  weather_cli-0.3.0.dist-info/
    METADATA            <- core metadata (name, version, dependencies...)
    WHEEL               <- wheel format version, generator, tags
    RECORD              <- every file with sha256 hash and size
    entry_points.txt    <- console scripts and plugins (optional)
    licenses/LICENSE    <- license files (modern backends)
  • METADATA: what you wrote in [project], translated (see Project Metadata Fields).
  • WHEEL: says Root-Is-Purelib: true for pure-Python content and lists the Tag: values from the filename.
  • RECORD: a CSV with path,sha256=<urlsafe-base64 digest>,size. Installers use it to verify files and to remove the package cleanly later. The RECORD file itself is listed with empty hash and size.
  • Installation is unpacking: pip copies files into purelib or platlib and writes .dist-info next to them. No code executes, which is why wheels install fast and safely.
flowchart LR
    S["source tree<br/>pyproject.toml + src/"] -- "build_wheel" --> W["name-ver-tag.whl<br/>(a zip)"]
    W --> A["package files"]
    W --> D["name-ver.dist-info/<br/>METADATA, WHEEL, RECORD"]
    W -- "pip install" --> I["unzip into site-packages"]

A wheel is the install layout, frozen into a zip.

Building a real wheel by hand

The function below does what a minimal backend does: collect files, create METADATA and WHEEL, compute RECORD, and write the zip. It then reads the wheel back and verifies every hash.

Python Create a wheel with zipfile and verify RECORD

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.

Because the zip entries have a fixed timestamp and a fixed order, running this twice produces byte-identical output. Real backends offer the same: setting SOURCE_DATE_EPOCH makes builds reproducible.

Installing the wheel you built

An installer would read this very file. Pyodide's micropip can install a wheel from the in-browser file system, so you can prove your hand-built wheel is a real one: it registers the distribution, and importlib.metadata can read it.

Python Install the hand-built wheel and use it

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.

You just did what python -m build followed by pip install does: pack files with metadata, then unpack them somewhere Python looks. Everything else a real backend adds (compiling extensions, computing tags, license files, reading pyproject.toml) sits on top of this.

Checking a build before you ship

Make a habit of three checks:

  1. List the contents. python -m zipfile -l dist/*.whl and tar tf dist/*.tar.gz. Are data files present, and tests, caches or secrets absent?
  2. Test in a clean environment. Create a fresh venv, pip install dist/*.whl, and run a smoke test from a different directory (not your project root).
  3. Validate metadata. twine check dist/* confirms that required fields exist and the README renders on PyPI.

Tools such as check-wheel-contents and check-manifest automate (1). In CI, run all three on every pull request, not only at release time.

Compiled wheels and tags

Pure-Python projects produce one py3-none-any wheel. Projects with C, Rust or Cython code produce a wheel per platform and Python version. Tools like cibuildwheel run these builds in CI on Linux, macOS and Windows and repair the wheels (auditwheel, delocate, delvewheel) so they bundle needed shared libraries. See Wheels, Sdists and the Package Index for tag meaning.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does python -m build produce by default?

    Building the wheel from the sdist proves the sdist contains everything needed.
  2. 2. What is the purpose of the RECORD file inside a wheel?

    Installers use RECORD to verify content and to know which files to remove.
  3. 3. Why does installing a wheel not run arbitrary project code?

    Unlike sdists, nothing is built at install time.
  4. 4. Which check best proves a wheel works for users?

    A clean install exposes missing files, wrong dependencies and path assumptions.

Summary

  • python -m build (or uv build) creates dist/*.tar.gz and dist/*.whl through the backend's PEP 517 hooks.
  • An sdist is a tar archive with PKG-INFO and source; a wheel is a zip with package files plus .dist-info (METADATA, WHEEL, RECORD).
  • RECORD lists sha256 hashes in urlsafe base64 without padding.
  • Installing a wheel only unpacks it; it does not run project code.
  • Always inspect the built files and test them in a clean environment.
  • Compiled projects need per-platform wheels, built in CI with tools such as cibuildwheel.

Next: Entry Points and Command-Line Tools