0
# Cibuildwheel
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: cibuildwheel
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install cibuildwheel`
10

11
## Core Imports
12

13
```python
14
import cibuildwheel  # Provides __version__
15
```
16

17
For programmatic usage:
18

19
```python
20
from cibuildwheel.architecture import Architecture
21
from cibuildwheel.errors import *  # All error classes
22
from cibuildwheel.options import Options, compute_options
23
from cibuildwheel.selector import BuildSelector
24
from cibuildwheel.typing import PlatformName, PLATFORMS
25
```
26

27
## Basic Usage
28

29
### Command Line Usage
30

31
```bash
32
# Install cibuildwheel
33
pip install cibuildwheel
34

35
# Build wheels for current platform
36
cibuildwheel
37

38
# Build for specific platform
39
cibuildwheel --platform linux
40

41
# Build for specific architectures
42
cibuildwheel --archs x86_64,aarch64
43

44
# Specify output directory
45
cibuildwheel --output-dir wheelhouse
46

47
# Build from specific package directory
48
cibuildwheel ./my-package
49
```
50

51
### CI Integration Example
52

53
```yaml
54
# GitHub Actions example
55
name: Build wheels
56

57
on: [push, pull_request]
58

59
jobs:
60
  build_wheels:
61
    name: Build wheels on ${{ matrix.os }}
62
    runs-on: ${{ matrix.os }}
63
    strategy:
64
      matrix:
65
        os: [ubuntu-latest, windows-latest, macos-latest]
66

67
    steps:
68
      - uses: actions/checkout@v4
69

70
      - uses: actions/setup-python@v4
71

72
      - name: Install cibuildwheel
73
        run: python -m pip install cibuildwheel
74

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

78
      - uses: actions/upload-artifact@v4
79
        with:
80
          name: wheels
81
          path: ./wheelhouse/*.whl
82
```
83

84
### Configuration via pyproject.toml
85

86
```toml
87
[tool.cibuildwheel]
88
# Build only for Python 3.9+
89
build = "cp39-* cp310-* cp311-* cp312-*"
90

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

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

97
# Environment variables
98
environment = { CFLAGS="-O2" }
99
```
100

101
## Architecture
102

103
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:
104

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

111
## Capabilities
112

113
### Command Line Interface
114

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

117
```python { .api }
118
def main() -> None
119
```
120

121
[Command Line Interface](./cli.md)
122

123
### Platform Support
124

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

127
```python { .api }
128
PlatformName = Literal["linux", "macos", "windows", "pyodide", "android", "ios"]
129
PLATFORMS: Final[frozenset[PlatformName]]
130

131
def native_platform() -> PlatformName
132
```
133

134
[Platform Support](./platforms.md)
135

136
### Architecture Management
137

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

140
```python { .api }
141
class Architecture(StrEnum):
142
    x86_64: str
143
    aarch64: str
144
    arm64: str
145
    # ... and many more
146
    
147
    @staticmethod
148
    def parse_config(config: str, platform: PlatformName) -> set[Architecture]
149
    
150
    @staticmethod 
151
    def native_arch(platform: PlatformName) -> Architecture | None
152
```
153

154
[Architecture Management](./architecture.md)
155

156
### Build Selection and Filtering
157

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

160
```python { .api }
161
@dataclasses.dataclass(frozen=True, kw_only=True)
162
class BuildSelector:
163
    build_config: str
164
    skip_config: str
165
    requires_python: SpecifierSet | None
166
    enable: frozenset[EnableGroup]
167
    
168
    def __call__(self, build_id: str) -> bool
169
```
170

171
[Build Selection](./build-selection.md)
172

173
### Configuration Management
174

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

177
```python { .api }
178
@dataclasses.dataclass(frozen=True, kw_only=True)
179
class Options:
180
    globals: GlobalOptions
181
    
182
def compute_options(platform: PlatformName, command_line_arguments: CommandLineArguments, env: Mapping[str, str]) -> Options
183
```
184

185
[Configuration](./configuration.md)
186

187
### Environment Handling
188

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

191
```python { .api }
192
@dataclasses.dataclass(kw_only=True)
193
class ParsedEnvironment:
194
    assignments: list[EnvironmentAssignment]
195
    
196
    def as_dictionary(self, prev_environment: Mapping[str, str], executor: bashlex_eval.EnvironmentExecutor | None = None) -> dict[str, str]
197

198
def parse_environment(env_string: str) -> ParsedEnvironment
199
```
200

201
[Environment Handling](./environment.md)
202

203
### Error Handling
204

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

207
```python { .api }
208
class FatalError(BaseException):
209
    return_code: int
210

211
class ConfigurationError(FatalError): ...
212
class NothingToDoError(FatalError): ...
213
# ... other specific error types
214
```
215

216
[Error Handling](./errors.md)
217

218
### CI Integration
219

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

222
```python { .api }
223
class CIProvider(Enum):
224
    github_actions: str
225
    azure_pipelines: str
226
    # ... other providers
227
    
228
def detect_ci_provider() -> CIProvider | None
229
```
230

231
[CI Integration](./ci-integration.md)
232

233
### Utility Functions
234

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

237
```python { .api }
238
def format_safe(template: str, **kwargs: str | os.PathLike[str]) -> str
239
def prepare_command(command: str, **kwargs: PathOrStr) -> str
240
def strtobool(val: str) -> bool
241
```
242

243
[Utilities](./utilities.md)