Platform Support

Cibuildwheel provides comprehensive cross-platform wheel building with native support for major operating systems and Python implementations.

Capabilities

Platform Detection

Automatic detection of the current platform for default build configuration.

def native_platform() -> PlatformName:
    """
    Detect the current platform based on sys.platform.
    
    Returns:
        PlatformName: One of "linux", "macos", "windows"
        
    Raises:
        ConfigurationError: If platform cannot be detected or is unsupported
    """

Platform Types

Core platform type definitions and constants.

PlatformName = Literal["linux", "macos", "windows", "pyodide", "android", "ios"]

PLATFORMS: Final[frozenset[PlatformName]] = frozenset({
    "linux", "macos", "windows", "pyodide", "android", "ios"
})

Build Identifier Generation

Generate build identifiers for specific platform configurations.

def get_build_identifiers(
    platform_module: PlatformModule,
    build_selector: BuildSelector,
    architectures: set[Architecture],
) -> list[str]:
    """
    Get list of build identifiers that match the selection criteria.
    
    Args:
        platform_module: Platform-specific implementation module
        build_selector: Build selection criteria
        architectures: Set of target architectures
        
    Returns:
        List of build identifier strings (e.g., ['cp311-linux_x86_64', 'cp312-linux_x86_64'])
    """

Platform Module Protocol

Interface that all platform modules must implement.

class PlatformModule(Protocol):
    def all_python_configurations(self) -> Sequence[GenericPythonConfiguration]:
        """Get all available Python configurations for this platform."""
        
    def get_python_configurations(
        self, build_selector: BuildSelector, architectures: set[Architecture]
    ) -> Sequence[GenericPythonConfiguration]:
        """Get Python configurations that match the selection criteria."""
        
    def build(self, options: Options, tmp_path: Path) -> None:
        """Execute the build process for this platform."""

Platform Module Registry

Registry of all available platform implementation modules.

ALL_PLATFORM_MODULES: Final[dict[PlatformName, PlatformModule]] = {
    "linux": linux,
    "windows": windows, 
    "macos": macos,
    "pyodide": pyodide,
    "android": android,
    "ios": ios,
}

Supported Platforms

Linux

Builds manylinux and musllinux wheels using Docker/Podman containers.

Supported Architectures:

• x86_64: 64-bit Intel/AMD (primary)
• i686: 32-bit Intel/AMD
• aarch64: 64-bit ARM
• ppc64le: 64-bit PowerPC Little Endian
• s390x: IBM System z
• armv7l: 32-bit ARM (experimental)
• riscv64: RISC-V 64-bit (experimental)

Python Implementations:

• CPython 3.8-3.14
• PyPy 3.8-3.11 (manylinux only)
• GraalPy 3.11 (manylinux only)

Key Features:

• Container-based builds for reproducibility
• auditwheel integration for dependency bundling
• Support for custom container images
• Cross-compilation via emulation (QEMU/binfmt_misc)

macOS

Builds universal and architecture-specific wheels for macOS.

Supported Architectures:

• x86_64: Intel Macs
• arm64: Apple Silicon Macs
• universal2: Universal binaries (both architectures)

Python Implementations:

• CPython 3.8-3.14
• PyPy 3.8-3.11
• GraalPy 3.11

Key Features:

• delocate integration for dependency bundling
• Support for multiple macOS deployment targets
• Universal binary creation
• Code signing support

Windows

Builds wheels for Windows across multiple architectures.

Supported Architectures:

• AMD64: 64-bit Windows (x86_64)
• x86: 32-bit Windows
• ARM64: Windows on ARM (experimental)

Python Implementations:

• CPython 3.8-3.14
• PyPy 3.8-3.11
• GraalPy 3.11

Key Features:

• Native Windows builds
• Support for Visual Studio Build Tools
• Cross-compilation for ARM64
• Chocolatey integration for dependencies

Pyodide

Builds wheels for the Pyodide WebAssembly platform.

Supported Architectures:

• wasm32: WebAssembly 32-bit

Python Implementations:

• CPython 3.12+ (experimental)

Key Features:

• WebAssembly compilation toolchain
• Emscripten integration
• Browser and Node.js compatibility
• Experimental PyPI support

Android

Builds wheels for Android devices and emulators.

Supported Architectures:

• arm64_v8a: 64-bit ARM for Android

Python Implementations:

• CPython 3.13+

Key Features:

• Android NDK integration
• Cross-compilation from Linux/macOS
• APK testing capabilities
• Termux compatibility

iOS

Builds wheels for iOS devices and simulators.

Supported Architectures:

• arm64_iphoneos: iOS devices (ARM64)
• arm64_iphonesimulator: iOS Simulator on Apple Silicon
• x86_64_iphonesimulator: iOS Simulator on Intel Macs

Python Implementations:

• CPython 3.13+

Key Features:

• Xcode integration
• iOS SDK targeting
• Simulator testing
• App Store deployment preparation

Platform-Specific Configuration

Container Configuration (Linux)

# Specify custom container images
CIBW_MANYLINUX_X86_64_IMAGE = "quay.io/pypa/manylinux2014_x86_64"
CIBW_MUSLLINUX_X86_64_IMAGE = "quay.io/pypa/musllinux_1_1_x86_64"

# Choose container engine
CIBW_CONTAINER_ENGINE = "docker"  # or "podman"

Cross-Compilation

# Linux ARM64 on x86_64 (requires emulation)
CIBW_ARCHS_LINUX = "x86_64 aarch64"

# Windows ARM64 (cross-compilation)
CIBW_ARCHS_WINDOWS = "AMD64 ARM64"

# macOS Universal binaries
CIBW_ARCHS_MACOS = "universal2"

Environment Pass-Through

# Pass host environment variables to containers
CIBW_ENVIRONMENT_PASS_LINUX = "SECRET_TOKEN API_KEY"

CI Platform Compatibility

Different CI platforms support different combinations of operating systems and architectures:

*Requires emulation setup