How to build a Python wheel
Building a wheel turns a Python project into a reusable package artifact that can move through CI, internal distribution, or offline installs without rebuilding the same source tree on every target host. Producing the wheel before deployment also exposes packaging mistakes while the project is still local and easy to fix.
Modern Python packaging reads the build backend and project metadata from pyproject.toml. Running python3 -m build --wheel asks the PyPA build frontend to create only the wheel in dist, using an isolated build environment derived from the project's [build-system] requirements; without --wheel, build normally produces both a source distribution and a wheel.
The steps below assume the project already has working package metadata and that the chosen interpreter or virtual environment is the one that should own the build module. On Windows, substitute py -m pip install --upgrade build and py -m build --wheel, and expect the wheel filename tags to change when the project includes compiled extensions or a stricter Requires-Python boundary.
Steps to build a Python wheel:
- Change into the project directory and confirm that pyproject.toml declares both the build backend and the package metadata.
$ cd ~/project $ sed -n '1,12p' pyproject.toml [build-system] requires = ["setuptools>=80"] build-backend = "setuptools.build_meta" [project] name = "billing-core" version = "1.4.2" description = "Client library for masked billing workflow integrations." readme = "README.md" requires-python = ">=3.11"
The project name, version, and build backend declared here drive the wheel filename and the metadata embedded in the finished archive.
- Install or upgrade the build frontend in the interpreter that should run the package build.
$ python3 -m pip install --upgrade build Collecting build Collecting packaging>=24.0 (from build) Collecting pyproject_hooks (from build) Installing collected packages: pyproject_hooks, packaging, build Successfully installed build-1.4.2 packaging-26.0 pyproject_hooks-1.2.0
build is a separate package from the standard library, so the command fails with No module named build until it is installed in the selected interpreter or virtual environment.
- Build only the wheel archive from the project root.
$ python3 -m build --wheel * Creating isolated environment: venv+pip... * Installing packages in isolated environment: - setuptools>=80 * Getting build dependencies for wheel... * Building wheel... ##### snipped ##### Successfully built billing_core-1.4.2-py3-none-any.whl
The build frontend creates an isolated environment from the project's [build-system] requirements before invoking the backend.
Use python -m build --wheel inside an active virtual environment when the project should be built with that environment's interpreter rather than the system python3.
- Confirm that the wheel was written to the default dist directory and read the compatibility tags in the filename.
$ ls dist/*.whl dist/billing_core-1.4.2-py3-none-any.whl
The py3-none-any suffix identifies a pure-Python wheel that is not tied to one operating system or CPU architecture. Projects with compiled extensions usually produce interpreter, ABI, and platform tags such as cp313-cp313-manylinux, macosx, or win_amd64 instead.
- Inspect the finished archive before handing it to CI or another host.
$ python3 -m zipfile -l dist/billing_core-1.4.2-py3-none-any.whl | sed -n '1,8p' File Name Modified Size billing_core/__init__.py 2026-03-29 04:03:18 69 billing_core-1.4.2.dist-info/METADATA 2026-03-29 04:03:54 260 billing_core-1.4.2.dist-info/WHEEL 2026-03-29 04:03:54 91 billing_core-1.4.2.dist-info/top_level.txt 2026-03-29 04:03:54 13 billing_core-1.4.2.dist-info/RECORD 2026-03-29 04:03:54 396
The presence of the package files together with the dist-info metadata confirms that the wheel contains the installable payload rather than only a filename in dist.