Getting Started

Installation

Install with pip or uv (recommended for speed):

pip install headless-wheel-builder

# or with uv
uv pip install headless-wheel-builder

# include all extras (notifications, security scanning, metrics)
pip install headless-wheel-builder[all]

Build your first wheel

From the current directory

hwb build .

From a git URL

Pin to a tag, branch, or commit:

hwb build https://github.com/user/repo@v2.0.0
hwb build https://github.com/user/repo@main

From a tarball

hwb build ./my-package-1.0.0.tar.gz

Multi-platform builds

Target multiple Python versions in a single invocation:

hwb build . --python 3.11 --python 3.12

Each version gets its own isolated environment. The resulting wheels land in dist/ by default.

Build isolation

Virtual environment (default)

Uses uv under the hood for fast dependency resolution:

hwb build . --isolation venv

Docker

Build inside a manylinux or musllinux container for maximum compatibility:

hwb build . --isolation docker --image manylinux2014_x86_64

Docker isolation ensures your wheels work on any Linux distribution without surprises.

Configuration

Add a [tool.hwb] section to your pyproject.toml:

[tool.hwb]
default-python = ["3.11", "3.12"]
isolation = "venv"
output-dir = "dist"

Command-line flags always override configuration file values.

Next steps

• Release Management — draft and approve releases
• CLI Reference — all 14 commands
• DevOps — pipelines, CI generation, multi-repo operations