0
# Platform Support
1

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

4
## Capabilities
5

6
### Platform Detection
7

8
Automatic detection of the current platform for default build configuration.
9

10
```python { .api }
11
def native_platform() -> PlatformName:
12
    """
13
    Detect the current platform based on sys.platform.
14
    
15
    Returns:
16
        PlatformName: One of "linux", "macos", "windows"
17
        
18
    Raises:
19
        ConfigurationError: If platform cannot be detected or is unsupported
20
    """
21
```
22

23
### Platform Types
24

25
Core platform type definitions and constants.
26

27
```python { .api }
28
PlatformName = Literal["linux", "macos", "windows", "pyodide", "android", "ios"]
29

30
PLATFORMS: Final[frozenset[PlatformName]] = frozenset({
31
    "linux", "macos", "windows", "pyodide", "android", "ios"
32
})
33
```
34

35
### Build Identifier Generation
36

37
Generate build identifiers for specific platform configurations.
38

39
```python { .api }
40
def get_build_identifiers(
41
    platform_module: PlatformModule,
42
    build_selector: BuildSelector,
43
    architectures: set[Architecture],
44
) -> list[str]:
45
    """
46
    Get list of build identifiers that match the selection criteria.
47
    
48
    Args:
49
        platform_module: Platform-specific implementation module
50
        build_selector: Build selection criteria
51
        architectures: Set of target architectures
52
        
53
    Returns:
54
        List of build identifier strings (e.g., ['cp311-linux_x86_64', 'cp312-linux_x86_64'])
55
    """
56
```
57

58
### Platform Module Protocol
59

60
Interface that all platform modules must implement.
61

62
```python { .api }
63
class PlatformModule(Protocol):
64
    def all_python_configurations(self) -> Sequence[GenericPythonConfiguration]:
65
        """Get all available Python configurations for this platform."""
66
        
67
    def get_python_configurations(
68
        self, build_selector: BuildSelector, architectures: set[Architecture]
69
    ) -> Sequence[GenericPythonConfiguration]:
70
        """Get Python configurations that match the selection criteria."""
71
        
72
    def build(self, options: Options, tmp_path: Path) -> None:
73
        """Execute the build process for this platform."""
74
```
75

76
### Platform Module Registry
77

78
Registry of all available platform implementation modules.
79

80
```python { .api }
81
ALL_PLATFORM_MODULES: Final[dict[PlatformName, PlatformModule]] = {
82
    "linux": linux,
83
    "windows": windows, 
84
    "macos": macos,
85
    "pyodide": pyodide,
86
    "android": android,
87
    "ios": ios,
88
}
89
```
90

91
## Supported Platforms
92

93
### Linux
94

95
Builds manylinux and musllinux wheels using Docker/Podman containers.
96

97
**Supported Architectures:**
98
- `x86_64`: 64-bit Intel/AMD (primary)
99
- `i686`: 32-bit Intel/AMD
100
- `aarch64`: 64-bit ARM
101
- `ppc64le`: 64-bit PowerPC Little Endian
102
- `s390x`: IBM System z
103
- `armv7l`: 32-bit ARM (experimental)
104
- `riscv64`: RISC-V 64-bit (experimental)
105

106
**Python Implementations:**
107
- CPython 3.8-3.14
108
- PyPy 3.8-3.11 (manylinux only)
109
- GraalPy 3.11 (manylinux only)
110

111
**Key Features:**
112
- Container-based builds for reproducibility
113
- auditwheel integration for dependency bundling
114
- Support for custom container images
115
- Cross-compilation via emulation (QEMU/binfmt_misc)
116

117
### macOS
118

119
Builds universal and architecture-specific wheels for macOS.
120

121
**Supported Architectures:**
122
- `x86_64`: Intel Macs
123
- `arm64`: Apple Silicon Macs
124
- `universal2`: Universal binaries (both architectures)
125

126
**Python Implementations:**
127
- CPython 3.8-3.14
128
- PyPy 3.8-3.11
129
- GraalPy 3.11
130

131
**Key Features:**
132
- delocate integration for dependency bundling
133
- Support for multiple macOS deployment targets
134
- Universal binary creation
135
- Code signing support
136

137
### Windows
138

139
Builds wheels for Windows across multiple architectures.
140

141
**Supported Architectures:**
142
- `AMD64`: 64-bit Windows (x86_64)
143
- `x86`: 32-bit Windows
144
- `ARM64`: Windows on ARM (experimental)
145

146
**Python Implementations:**
147
- CPython 3.8-3.14
148
- PyPy 3.8-3.11
149
- GraalPy 3.11
150

151
**Key Features:**
152
- Native Windows builds
153
- Support for Visual Studio Build Tools
154
- Cross-compilation for ARM64
155
- Chocolatey integration for dependencies
156

157
### Pyodide
158

159
Builds wheels for the Pyodide WebAssembly platform.
160

161
**Supported Architectures:**
162
- `wasm32`: WebAssembly 32-bit
163

164
**Python Implementations:**
165
- CPython 3.12+ (experimental)
166

167
**Key Features:**
168
- WebAssembly compilation toolchain
169
- Emscripten integration
170
- Browser and Node.js compatibility
171
- Experimental PyPI support
172

173
### Android
174

175
Builds wheels for Android devices and emulators.
176

177
**Supported Architectures:**
178
- `arm64_v8a`: 64-bit ARM for Android
179

180
**Python Implementations:**
181
- CPython 3.13+
182

183
**Key Features:**
184
- Android NDK integration
185
- Cross-compilation from Linux/macOS
186
- APK testing capabilities
187
- Termux compatibility
188

189
### iOS
190

191
Builds wheels for iOS devices and simulators.
192

193
**Supported Architectures:**
194
- `arm64_iphoneos`: iOS devices (ARM64)
195
- `arm64_iphonesimulator`: iOS Simulator on Apple Silicon
196
- `x86_64_iphonesimulator`: iOS Simulator on Intel Macs
197

198
**Python Implementations:**
199
- CPython 3.13+
200

201
**Key Features:**
202
- Xcode integration
203
- iOS SDK targeting
204
- Simulator testing
205
- App Store deployment preparation
206

207
## Platform-Specific Configuration
208

209
### Container Configuration (Linux)
210

211
```python
212
# Specify custom container images
213
CIBW_MANYLINUX_X86_64_IMAGE = "quay.io/pypa/manylinux2014_x86_64"
214
CIBW_MUSLLINUX_X86_64_IMAGE = "quay.io/pypa/musllinux_1_1_x86_64"
215

216
# Choose container engine
217
CIBW_CONTAINER_ENGINE = "docker"  # or "podman"
218
```
219

220
### Cross-Compilation
221

222
```python
223
# Linux ARM64 on x86_64 (requires emulation)
224
CIBW_ARCHS_LINUX = "x86_64 aarch64"
225

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

229
# macOS Universal binaries
230
CIBW_ARCHS_MACOS = "universal2"
231
```
232

233
### Environment Pass-Through
234

235
```python
236
# Pass host environment variables to containers
237
CIBW_ENVIRONMENT_PASS_LINUX = "SECRET_TOKEN API_KEY"
238
```
239

240
## CI Platform Compatibility
241

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

244
| CI Platform | Linux | macOS | Windows | Linux ARM | macOS ARM | Windows ARM | Android | iOS |
245
|-------------|-------|-------|---------|-----------|-----------|-------------|---------|-----|
246
| GitHub Actions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
247
| Azure Pipelines | ✅ | ✅ | ✅ | - | ✅ | ✅ | ✅ | ✅ |
248
| Travis CI | ✅ | - | ✅ | ✅ | - | - | ✅ | - |
249
| CircleCI | ✅ | ✅ | - | ✅ | ✅ | - | ✅ | ✅ |
250
| GitLab CI | ✅ | ✅ | ✅ | ✅* | ✅ | - | ✅ | ✅ |
251
| Cirrus CI | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ | - |
252
253
*Requires emulation setup