CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-cibuildwheel

Build Python wheels on CI with minimal configuration.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

Cibuildwheel

A comprehensive CI-native tool for building Python wheels across multiple platforms, operating systems, and Python versions with minimal configuration. Cibuildwheel automates the complex process of creating distributable Python packages (wheels) on continuous integration servers.

Package Information

  • Package Name: cibuildwheel
  • Package Type: pypi
  • Language: Python
  • Installation: pip install cibuildwheel

Core Imports

import cibuildwheel  # Provides __version__

For programmatic usage:

from cibuildwheel.architecture import Architecture
from cibuildwheel.errors import *  # All error classes
from cibuildwheel.options import Options, compute_options
from cibuildwheel.selector import BuildSelector
from cibuildwheel.typing import PlatformName, PLATFORMS

Basic Usage

Command Line Usage

# Install cibuildwheel
pip install cibuildwheel

# Build wheels for current platform
cibuildwheel

# Build for specific platform
cibuildwheel --platform linux

# Build for specific architectures
cibuildwheel --archs x86_64,aarch64

# Specify output directory
cibuildwheel --output-dir wheelhouse

# Build from specific package directory
cibuildwheel ./my-package

CI Integration Example

# GitHub Actions example
name: Build wheels

on: [push, pull_request]

jobs:
  build_wheels:
    name: Build wheels on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v4

      - name: Install cibuildwheel
        run: python -m pip install cibuildwheel

      - name: Build wheels
        run: python -m cibuildwheel --output-dir wheelhouse

      - uses: actions/upload-artifact@v4
        with:
          name: wheels
          path: ./wheelhouse/*.whl

Configuration via pyproject.toml

[tool.cibuildwheel]
# Build only for Python 3.9+
build = "cp39-* cp310-* cp311-* cp312-*"

# Skip 32-bit builds
skip = "*-win32 *-manylinux_i686"

# Test command
test-command = "pytest {project}/tests"

# Environment variables
environment = { CFLAGS="-O2" }

Architecture

Cibuildwheel operates on a platform-module architecture where each supported platform (Linux, macOS, Windows, iOS, Android, Pyodide) has its own specialized build module. The tool:

  1. Detects or accepts target platform specification
  2. Selects Python configurations based on build selectors and architecture requirements
  3. Manages build environments including containers for Linux and virtual environments for other platforms
  4. Orchestrates the build process including dependency installation, wheel building, and testing
  5. Handles wheel repair through platform-specific tools like auditwheel and delocate

Capabilities

Command Line Interface

The primary interface for running cibuildwheel with comprehensive options for platform selection, architecture specification, build filtering, and output configuration.

def main() -> None

Command Line Interface

Platform Support

Cross-platform wheel building with native support for major operating systems and architectures, including emulation support for cross-compilation.

PlatformName = Literal["linux", "macos", "windows", "pyodide", "android", "ios"]
PLATFORMS: Final[frozenset[PlatformName]]

def native_platform() -> PlatformName

Platform Support

Architecture Management

Comprehensive architecture support with automatic detection, cross-compilation capabilities, and architecture-specific build configuration.

class Architecture(StrEnum):
    x86_64: str
    aarch64: str
    arm64: str
    # ... and many more
    
    @staticmethod
    def parse_config(config: str, platform: PlatformName) -> set[Architecture]
    
    @staticmethod 
    def native_arch(platform: PlatformName) -> Architecture | None

Architecture Management

Build Selection and Filtering

Advanced pattern-based build selection system for controlling which Python versions, platforms, and architectures to build for.

@dataclasses.dataclass(frozen=True, kw_only=True)
class BuildSelector:
    build_config: str
    skip_config: str
    requires_python: SpecifierSet | None
    enable: frozenset[EnableGroup]
    
    def __call__(self, build_id: str) -> bool

Build Selection

Configuration Management

Comprehensive configuration system supporting TOML files, environment variables, and command-line options with validation and schema support.

@dataclasses.dataclass(frozen=True, kw_only=True)
class Options:
    globals: GlobalOptions
    
def compute_options(platform: PlatformName, command_line_arguments: CommandLineArguments, env: Mapping[str, str]) -> Options

Configuration

Environment Handling

Advanced environment variable parsing with bash syntax support and context-aware evaluation for build customization.

@dataclasses.dataclass(kw_only=True)
class ParsedEnvironment:
    assignments: list[EnvironmentAssignment]
    
    def as_dictionary(self, prev_environment: Mapping[str, str], executor: bashlex_eval.EnvironmentExecutor | None = None) -> dict[str, str]

def parse_environment(env_string: str) -> ParsedEnvironment

Environment Handling

Error Handling

Structured exception hierarchy with specific error types and return codes for different failure scenarios.

class FatalError(BaseException):
    return_code: int

class ConfigurationError(FatalError): ...
class NothingToDoError(FatalError): ...
# ... other specific error types

Error Handling

CI Integration

Built-in support for major CI/CD platforms with platform-specific optimizations and output formatting.

class CIProvider(Enum):
    github_actions: str
    azure_pipelines: str
    # ... other providers
    
def detect_ci_provider() -> CIProvider | None

CI Integration

Utility Functions

Helper functions for string formatting, command preparation, version parsing, and other common operations.

def format_safe(template: str, **kwargs: str | os.PathLike[str]) -> str
def prepare_command(command: str, **kwargs: PathOrStr) -> str
def strtobool(val: str) -> bool

Utilities

Install with Tessl CLI

npx tessl i tessl/pypi-cibuildwheel
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/cibuildwheel@3.1.x
Publish Source
CLI
Badge
tessl/pypi-cibuildwheel badge