Building with Python's Build Tool

Building with Python's Build Tool

Overview

The build module is Python's official standards-compliant build tool, providing a simple interface for building packages from any PEP 517-compatible backend including Hatchling. Reference this when helping users understand build isolation, configuration options, CI/CD integration, and the comparison with direct hatch build commands.

Installation

# Install the build module
pip install build

# Or with pipx for isolated installation
pipx install build

# Verify installation
python -m build --version

Basic Usage

Build All Formats

# Build both sdist and wheel (default)
python -m build

# Equivalent to
python -m build --sdist --wheel

Build Specific Formats

# Build only source distribution
python -m build --sdist

# Build only wheel
python -m build --wheel

# Build from a specific directory
python -m build /path/to/project

Command-Line Options

Output Directory

# Specify output directory (default: dist/)
python -m build --outdir build/
python -m build -o custom_dist/

# Build in a specific directory
python -m build --wheel --outdir wheels/
python -m build --sdist --outdir source/

Build Isolation

# Build with isolation (default)
python -m build

# Build without isolation (uses current environment)
python -m build --no-isolation

# Skip dependency check
python -m build --skip-dependency-check

Configuration Settings

# Pass configuration to the backend
python -m build --config-setting="--option=value"

# Multiple config settings
python -m build \
  --config-setting="--build-option=value1" \
  --config-setting="--global-option=value2"

# Example for limited API
python -m build -w --config-setting="--build-option=--py-limited-api=cp37"

Working with pyproject.toml

The build tool reads configuration from pyproject.toml:

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

[project]
name = "my-package"
version = "0.1.0"
description = "My Python package"

Build Process

What Happens During Build

1. Create isolated environment (unless --no-isolation)
2. Install build dependencies from build-system.requires
3. Call the build backend specified in build-backend
4. Generate artifacts in the output directory

Build Output

$ python -m build
* Creating venv isolated environment...
* Installing packages in isolated environment... (hatchling)
* Getting build dependencies for sdist...
* Building sdist...
* Building wheel from sdist
* Creating venv isolated environment...
* Installing packages in isolated environment... (hatchling)
* Getting build dependencies for wheel...
* Building wheel...
Successfully built my_package-0.1.0.tar.gz and my_package-0.1.0-py3-none-any.whl

Advanced Usage

Verbose Output

# Show detailed build information
python -m build --verbose

# Quiet mode (minimal output)
python -m build --quiet

Building from Source Distribution

# Extract an sdist first
tar -xzf dist/package-1.0.0.tar.gz

# Build wheel from extracted sdist
python -m build --wheel package-1.0.0/

Environment Variables

# Set SOURCE_DATE_EPOCH for reproducible builds
SOURCE_DATE_EPOCH=1609459200 python -m build

# Specify pip cache directory
PIP_CACHE_DIR=.cache python -m build

# Use custom index URL
PIP_INDEX_URL=https://pypi.org/simple python -m build

Integration with Hatchling

When using Hatchling as the backend:

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

[tool.hatch.build]
# Hatchling-specific configuration
directory = "dist"
reproducible = true

Hatchling Configuration via Build

# Pass Hatchling-specific options
python -m build --config-setting="--target=wheel"

# Build specific Hatchling target
python -m build --wheel --config-setting="--target=wheel:editable"

Comparison with Hatch Build

CI/CD Examples

GitHub Actions

name: Build Package

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.x"

      - name: Install build
        run: pip install build

      - name: Build package
        run: python -m build

      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

GitLab CI

build:
  stage: build
  image: python:3.11
  script:
    - pip install build
    - python -m build --outdir artifacts/
  artifacts:
    paths:
      - artifacts/

Local Build Script

#!/bin/bash
# build.sh

set -e

echo "Installing build dependencies..."
pip install --upgrade pip build

echo "Cleaning previous builds..."
rm -rf dist/ build/

echo "Building package..."
python -m build

echo "Verifying build artifacts..."
ls -la dist/

echo "Build complete!"

Docker Build

# Dockerfile for building Python package
FROM python:3.11-slim

WORKDIR /build

# Install build tool
RUN pip install --no-cache-dir build

# Copy project files
COPY pyproject.toml README.md ./
COPY src/ ./src/

# Build package
RUN python -m build --wheel --outdir /dist

# Final stage
FROM scratch
COPY --from=0 /dist/*.whl /

Troubleshooting

Common Issues

1. Missing build module

   pip install --upgrade build
   

2. Build dependency conflicts

   # Use isolation to avoid conflicts
   python -m build
   # Or upgrade pip and setuptools
   pip install --upgrade pip setuptools
   

3. Permission errors

   # Use --user flag or virtual environment
   pip install --user build
   # Or
   python -m venv venv && source venv/bin/activate
   

4. Backend not found

   # Ensure build-system is properly configured
   [build-system]
   requires = ["hatchling"]
   build-backend = "hatchling.build"
   

Best Practices

1. Always use build isolation for reproducible builds
2. Test both sdist and wheel formats
3. Verify output with tar -tzf (sdist) and unzip -l (wheel)
4. Use CI/CD for automated building
5. Clean previous builds before release builds
6. Document build requirements in pyproject.toml

PEP 517 Compliance

The build module ensures PEP 517 compliance:

• Reads pyproject.toml for build configuration
• Creates isolated build environments
• Calls standard backend hooks
• Produces standard-compliant artifacts

See Also

• PEP 517 - Build System Interface
• Python Build Documentation
• Building with Hatch
• Build Output Customization