BD002: WheelBuilds

Overview

Property Value
ID BD002
Name WheelBuilds
Group build
Severity ERROR

Description

Verifies that a wheel (.whl) file can be built successfully.

Wheels are the preferred distribution format for Python packages because:

  • They install faster than source distributions
  • They don’t require build tools on the user’s machine
  • They are pre-compiled and platform-specific when needed
  • PyPI strongly prefers wheel uploads

What it checks

The check runs python -m build --wheel and:

  • PASSED: Build completes and a .whl file is created
  • FAILED: Build fails or no .whl file is produced
  • NOT_APPLICABLE: No pyproject.toml found or build package not installed

How to fix

Install the build package

pip install build
# or
uv add --dev build

Run wheel build locally

python -m build --wheel

Common failure causes

  1. Build backend misconfiguration: Incorrect build-backend setting
  2. Missing source files: Package discovery not finding files
  3. Invalid package structure: Files not in expected locations
  4. MANIFEST.in issues: Files excluded from wheel incorrectly

Configure package discovery

For hatchling, ensure your package is discoverable:

[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]

For setuptools:

[tool.setuptools.packages.find]
where = ["src"]

Check wheel contents

After building, inspect the wheel:

python -m build --wheel
unzip -l dist/*.whl

Verify your source files are included.

Why ERROR severity?

This check is an ERROR because:

  • PyPI expects wheel uploads for most packages
  • Installation without wheels is slower and may fail
  • Missing wheels can block users on certain platforms

Configuration

Timeout

The default build timeout is 300 seconds (5 minutes):

[tool.pycmdcheck.checks.BD002]
timeout = 600  # 10 minutes

Skip this check

[tool.pycmdcheck]
skip = ["BD002"]

CLI

pycmdcheck --skip BD002