Command Line Interface

Cibuildwheel provides a comprehensive command-line interface for building Python wheels across multiple platforms and architectures.

Capabilities

Main Command

The primary entry point for cibuildwheel operations.

def main() -> None:
    """
    Main CLI entry point for cibuildwheel.
    
    Parses command line arguments, validates configuration,
    and orchestrates the wheel building process.
    
    Raises:
        FatalError: On configuration errors or build failures
    """

def main_inner(global_options: GlobalOptions) -> None:
    """
    Internal main function that performs the actual build logic.
    
    Same as main() but raises FatalError exceptions rather than 
    exiting directly, allowing for custom error handling.
    
    Args:
        global_options: Global build options and configuration
        
    Raises:
        FatalError: On configuration errors or build failures
    """

Command Line Arguments

Platform Selection

cibuildwheel --platform <platform>

Choose the target platform for wheel building:

• auto (default): Auto-detect current platform
• linux: Build for Linux using containers
• macos: Build for macOS (requires macOS runner)
• windows: Build for Windows (requires Windows runner)
• pyodide: Build for Pyodide WebAssembly
• android: Build for Android
• ios: Build for iOS (requires macOS runner)

Architecture Selection

cibuildwheel --archs <architectures>

Specify target CPU architectures (comma-separated):

• auto (default): Build for architectures natively supported
• native: Build only for the current machine's architecture
• all: Build for all supported architectures on the platform
• auto64: Build for 64-bit architectures only
• auto32: Build for 32-bit architectures only
• Specific architectures: x86_64,aarch64,arm64,i686,etc.

Build Selection

cibuildwheel --only <identifier>

Force building a single wheel by its build identifier (e.g., cp311-linux_x86_64). This overrides CIBW_BUILD/CIBW_SKIP settings.

cibuildwheel --enable <group>

Enable additional categories of builds (can be used multiple times):

• cpython-prerelease: Include CPython prerelease versions
• pypy: Include PyPy builds
• graalpy: Include GraalPy builds
• cpython-freethreading: Include free-threaded CPython

Output Configuration

cibuildwheel --output-dir <directory>

Specify destination folder for built wheels (default: wheelhouse).

Configuration

cibuildwheel --config-file <path>

Specify TOML configuration file path. Default is {package}/pyproject.toml if it exists.

Package Source

cibuildwheel [PACKAGE]

Path to the package directory or SDist file. Default is the current working directory.

Utility Options

cibuildwheel --print-build-identifiers

Print the build identifiers that match the current configuration and exit without building.

cibuildwheel --clean-cache

Clear the cibuildwheel cache directory and exit.

cibuildwheel --allow-empty

Don't report an error if no wheels match the build selection criteria.

cibuildwheel --debug-traceback

Print full Python tracebacks for all errors (useful for debugging).

Usage Examples

Basic Usage

# Build wheels for current platform
cibuildwheel

# Build for specific platform
cibuildwheel --platform linux

# Build specific Python versions only
cibuildwheel --only cp311-linux_x86_64

Cross-Platform Building

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

# Build for all 64-bit architectures
cibuildwheel --archs auto64

# Build for Linux with emulation
cibuildwheel --platform linux --archs x86_64,aarch64,ppc64le

Advanced Configuration

# Use custom config file
cibuildwheel --config-file custom-build.toml

# Custom output directory
cibuildwheel --output-dir dist/wheels

# Enable prerelease Python versions
cibuildwheel --enable cpython-prerelease

# Debug mode with full tracebacks
cibuildwheel --debug-traceback

CI Integration

# GitHub Actions matrix build
cibuildwheel --platform ${{ matrix.platform }} --output-dir wheelhouse

# Build from SDist
cibuildwheel package-1.0.0.tar.gz --output-dir wheels

Inspection and Debugging

# See what would be built
cibuildwheel --print-build-identifiers

# Clean cache if needed
cibuildwheel --clean-cache

# Allow empty builds (useful for conditional CI)
cibuildwheel --allow-empty

Return Codes

The cibuildwheel command returns specific exit codes for different error conditions:

• 0: Success
• 1: General fatal error
• 2: Configuration error
• 3: No builds matched selection criteria
• 4: Deprecated configuration detected
• 5: Non-platform wheel detected
• 6: Wheel already exists (when configured to fail)
• 7: Container engine too old
• 8: Wheel repair step failed

Environment Variables

Many CLI options can also be controlled via environment variables with the CIBW_ prefix:

• CIBW_PLATFORM: Equivalent to --platform
• CIBW_ARCHS: Equivalent to --archs
• CIBW_OUTPUT_DIR: Equivalent to --output-dir
• CIBW_CONFIG_FILE: Equivalent to --config-file
• CIBW_DEBUG_TRACEBACK: Equivalent to --debug-traceback

Plus many more configuration options for fine-tuning the build process.