0
# Build Selection
1

2
Cibuildwheel provides a powerful pattern-based build selection system for controlling which Python versions, platforms, and architectures to build for.
3

4
## Capabilities
5

6
### Build Selector
7

8
Main interface for controlling which builds are executed.
9

10
```python { .api }
11
@dataclasses.dataclass(frozen=True, kw_only=True)
12
class BuildSelector:
13
    build_config: str
14
    skip_config: str
15
    requires_python: SpecifierSet | None = None
16
    enable: frozenset[EnableGroup] = frozenset()
17
    
18
    def __call__(self, build_id: str) -> bool:
19
        """
20
        Test if a build identifier should be built.
21
        
22
        Args:
23
            build_id: Build identifier string (e.g., 'cp311-linux_x86_64')
24
            
25
        Returns:
26
            True if the build should be executed, False otherwise
27
        """
28
```
29

30
### Test Selector
31

32
Controls which builds should have tests executed.
33

34
```python { .api }
35
@dataclasses.dataclass(frozen=True, kw_only=True)
36
class TestSelector:
37
    skip_config: str
38
    
39
    def __call__(self, build_id: str) -> bool:
40
        """
41
        Test if a build should be tested.
42
        
43
        Args:
44
            build_id: Build identifier string
45
            
46
        Returns:
47
            True if tests should be run for this build, False otherwise
48
        """
49
```
50

51
### Pattern Matching
52

53
Low-level pattern matching function for build selectors.
54

55
```python { .api }
56
def selector_matches(patterns: str, string: str) -> bool:
57
    """
58
    Test if any pattern in a space-separated list matches a string.
59
    
60
    Args:
61
        patterns: Space-separated list of glob patterns
62
        string: String to test against patterns
63
        
64
    Returns:
65
        True if any pattern matches, False otherwise
66
    """
67
```
68

69
### Enable Groups
70

71
Categories of builds that can be optionally enabled.
72

73
```python { .api }
74
class EnableGroup(StrEnum):
75
    CPythonExperimentalRiscV64 = "cpython-experimental-riscv64"
76
    CPythonFreeThreading = "cpython-freethreading"
77
    CPythonPrerelease = "cpython-prerelease"
78
    GraalPy = "graalpy"
79
    PyPy = "pypy"
80
    PyPyEoL = "pypy-eol"
81
    PyodidePrerelease = "pyodide-prerelease"
82
```
83

84
## Build Identifier Format
85

86
Build identifiers follow the pattern: `{python_tag}-{platform_tag}`
87

88
### Python Tags
89

90
- **CPython**: `cp38`, `cp39`, `cp310`, `cp311`, `cp312`, `cp313`, `cp314`
91
- **PyPy**: `pp38`, `pp39`, `pp310`, `pp311`
92
- **GraalPy**: `graalpy311`
93

94
### Platform Tags
95

96
- **Linux**: `linux_x86_64`, `linux_i686`, `linux_aarch64`, `linux_ppc64le`, `linux_s390x`, `linux_armv7l`, `linux_riscv64`
97
- **macOS**: `macosx_x86_64`, `macosx_arm64`, `macosx_universal2`
98
- **Windows**: `win_amd64`, `win32`, `win_arm64`
99
- **Pyodide**: `pyodide_wasm32`
100
- **Android**: `android_arm64_v8a`
101
- **iOS**: `ios_arm64_iphoneos`, `ios_arm64_iphonesimulator`, `ios_x86_64_iphonesimulator`
102

103
## Configuration Patterns
104

105
### Build Selection Patterns
106

107
```python
108
# Build specific Python versions
109
CIBW_BUILD = "cp39-* cp310-* cp311-*"
110

111
# Build for specific platforms
112
CIBW_BUILD = "*-linux_x86_64 *-macosx_x86_64"
113

114
# Build specific combinations
115
CIBW_BUILD = "cp311-linux_x86_64 cp311-macosx_arm64"
116
```
117

118
### Skip Patterns
119

120
```python
121
# Skip 32-bit builds
122
CIBW_SKIP = "*-win32 *-linux_i686"
123

124
# Skip PyPy builds
125
CIBW_SKIP = "pp*"
126

127
# Skip specific Python versions
128
CIBW_SKIP = "cp38-* cp39-*"
129

130
# Skip experimental architectures
131
CIBW_SKIP = "*-linux_riscv64 *-linux_armv7l"
132
```
133

134
### Test Skip Patterns
135

136
```python
137
# Skip tests for slow architectures
138
CIBW_TEST_SKIP = "*-linux_ppc64le *-linux_s390x"
139

140
# Skip tests for emulated builds
141
CIBW_TEST_SKIP = "*-linux_aarch64"
142

143
# Skip tests for specific Python versions
144
CIBW_TEST_SKIP = "cp38-*"
145
```
146

147
## Enable Groups
148

149
### CPython Prerelease
150

151
Enable building with prerelease CPython versions:
152

153
```python
154
CIBW_ENABLE = "cpython-prerelease"
155
# Or in pyproject.toml:
156
# enable = ["cpython-prerelease"]
157
```
158

159
### PyPy Support
160

161
Enable PyPy builds (disabled by default):
162

163
```python
164
CIBW_ENABLE = "pypy"
165
# Enables: pp38, pp39, pp310, pp311
166
```
167

168
### GraalPy Support
169

170
Enable GraalPy builds:
171

172
```python
173
CIBW_ENABLE = "graalpy"
174
# Enables: graalpy311
175
```
176

177
### Free-threaded CPython
178

179
Enable CPython builds with free-threading (Python 3.13+):
180

181
```python
182
CIBW_ENABLE = "cpython-freethreading"
183
# Enables: cp313t (free-threaded variant)
184
```
185

186
### Experimental RISC-V
187

188
Enable experimental RISC-V 64-bit builds:
189

190
```python 
191
CIBW_ENABLE = "cpython-experimental-riscv64"
192
# Note: This enable group is deprecated
193
```
194

195
### Multiple Enable Groups
196

197
```python
198
CIBW_ENABLE = "pypy graalpy cpython-prerelease"
199
```
200

201
## Advanced Selection Examples
202

203
### Platform-Specific Selection
204

205
```toml
206
[tool.cibuildwheel]
207
# Global build configuration
208
build = "cp39-* cp310-* cp311-*"
209

210
[tool.cibuildwheel.linux]
211
# Linux-specific overrides
212
build = "cp39-* cp310-* cp311-* cp312-*"
213
skip = "*-linux_i686"  # Skip 32-bit Linux
214

215
[tool.cibuildwheel.windows]
216
# Windows-specific overrides  
217
skip = "*-win32"  # Skip 32-bit Windows
218

219
[tool.cibuildwheel.macos]
220
# macOS-specific overrides
221
build = "cp310-* cp311-*"  # Only newer Python versions
222
```
223

224
### Architecture-Specific Selection
225

226
```python
227
# Build matrix excluding slow combinations
228
CIBW_BUILD = "cp311-linux_x86_64 cp311-linux_aarch64 cp311-macosx_* cp311-win_amd64"
229

230
# Skip tests on emulated architectures to save time
231
CIBW_TEST_SKIP = "*-linux_aarch64 *-linux_ppc64le *-linux_s390x"
232
```
233

234
### Conditional Selection
235

236
```python
237
# Use environment variables for conditional selection
238
import os
239

240
if os.environ.get("CIBW_QUICK_BUILD"):
241
    # Quick build: only test current Python version
242
    CIBW_BUILD = f"cp{sys.version_info.major}{sys.version_info.minor}-*"
243
else:
244
    # Full build: all supported versions
245
    CIBW_BUILD = "cp39-* cp310-* cp311-* cp312-*"
246
```
247

248
### Requirements-based Selection
249

250
```python
251
# Select builds based on project's requires-python
252
from packaging.specifiers import SpecifierSet
253

254
# Automatically skip unsupported Python versions
255
requires_python = SpecifierSet(">=3.10")
256
```
257

258
## Build Selection Validation
259

260
Cibuildwheel validates build selectors and provides warnings for common issues:
261

262
### Invalid Selectors
263

264
```python
265
# This would generate a warning
266
CIBW_BUILD = "cp37-*"  # Python 3.7 not supported in cibuildwheel 3.x
267

268
# This would generate an error  
269
CIBW_SKIP = "invalid-selector"  # Invalid pattern
270
```
271

272
### Empty Selection
273

274
```python
275
# If no builds match, cibuildwheel will error unless:
276
CIBW_ALLOW_EMPTY = "1"  # Allow empty build selection
277
```
278

279
### Enable Group Validation
280

281
```python
282
# Using enable groups without enabling them generates warnings
283
CIBW_BUILD = "pp39-*"  # Warning: PyPy not enabled
284
CIBW_ENABLE = "pypy"   # Required to actually build PyPy
285
```
286

287
## Usage Examples
288

289
### Minimal Configuration
290

291
```python
292
# Build for Python 3.11+ only, skip 32-bit
293
CIBW_BUILD = "cp311-* cp312-*"
294
CIBW_SKIP = "*-win32 *-linux_i686"
295
```
296

297
### Full Matrix Build
298

299
```python
300
# Build everything possible
301
CIBW_ENABLE = "pypy graalpy cpython-prerelease"
302
CIBW_BUILD = "*"
303
CIBW_SKIP = ""  # Don't skip anything
304
```
305

306
### Targeted Build
307

308
```python
309
# Build only for specific deployment targets
310
CIBW_BUILD = "cp311-linux_x86_64 cp311-macosx_universal2 cp311-win_amd64"
311
CIBW_TEST_COMMAND = "pytest"
312
```
313

314
### Development Build
315

316
```python
317
# Quick build for development/testing
318
CIBW_BUILD = "cp311-*"  # Current Python version only
319
CIBW_ARCHS = "native"   # Native architecture only
320
CIBW_TEST_SKIP = "*"    # Skip all tests
321
```