BD001: BuildSucceeds

Overview

Property Value
ID BD001
Name BuildSucceeds
Group build
Severity ERROR

Description

Verifies that the package can be built successfully using python -m build.

A successful build is essential because:

  • It confirms your build configuration is correct
  • It ensures the package can be distributed via PyPI
  • It catches missing files or incorrect metadata early
  • It validates that build dependencies are properly declared

What it checks

The check runs python -m build and:

  • PASSED: Build completes with exit code 0
  • FAILED: Build fails (reports error output)
  • 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

Ensure pyproject.toml exists

Create a minimal pyproject.toml:

[project]
name = "my-package"
version = "0.1.0"
requires-python = ">=3.11"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Run build locally

python -m build

Common failure causes

  1. Missing build backend: No [build-system] section in pyproject.toml
  2. Invalid metadata: Missing required fields like name or version
  3. Missing source files: Package source not found by build backend
  4. Syntax errors: Python files with syntax errors can break build
  5. Missing build dependencies: Build-time requirements not declared

Configure build backend

Choose a build backend that fits your project:

Hatchling (modern, recommended):

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Setuptools:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

Poetry:

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Why ERROR severity?

This check is an ERROR because:

  • A package that cannot be built cannot be distributed
  • Build failures block releases to PyPI
  • Users cannot install your package if it fails to build

Configuration

Timeout

The default build timeout is 300 seconds (5 minutes). For complex packages:

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

Skip this check

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

CLI

pycmdcheck --skip BD001