0
# Configuration
1

2
Cibuildwheel provides a comprehensive configuration system supporting TOML files, environment variables, and command-line options with validation and schema support.
3

4
## Capabilities
5

6
### Options Container
7

8
Main container for all build configuration options.
9

10
```python { .api }
11
@dataclasses.dataclass(frozen=True, kw_only=True)
12
class Options:
13
    globals: GlobalOptions
14
    
15
    def build_options(self, identifier: str) -> BuildOptions:
16
        """
17
        Get build-specific options for a given build identifier.
18
        
19
        Args:
20
            identifier: Build identifier (e.g., 'cp311-linux_x86_64')
21
            
22
        Returns:
23
            BuildOptions instance with configuration for this build
24
        """
25
    
26
    def check_for_invalid_configuration(self, identifiers: Sequence[str]) -> None:
27
        """
28
        Validate configuration against actual build identifiers.
29
        
30
        Args:
31
            identifiers: List of build identifiers that will be built
32
            
33
        Raises:
34
            ValueError: If configuration contains invalid settings
35
        """
36
    
37
    def summary(self, identifiers: Sequence[str]) -> str:
38
        """
39
        Generate a human-readable summary of the configuration.
40
        
41
        Args:
42
            identifiers: List of build identifiers
43
            
44
        Returns:
45
            Formatted string summarizing the build configuration
46
        """
47
```
48

49
### Global Options
50

51
Configuration that applies to all builds.
52

53
```python { .api }
54
@dataclasses.dataclass(frozen=True, kw_only=True)
55
class GlobalOptions:
56
    package_dir: Path
57
    output_dir: Path
58
    build_selector: BuildSelector
59
    test_selector: TestSelector
60
    architectures: set[Architecture]
61
    allow_empty: bool
62
```
63

64
### Build Options
65

66
Configuration specific to individual builds.
67

68
```python { .api }
69
@dataclasses.dataclass(frozen=True, kw_only=True)
70
class BuildOptions:
71
    globals: GlobalOptions
72
    environment: ParsedEnvironment
73
    build_frontend: BuildFrontendConfig
74
    dependency_constraints: DependencyConstraints | None
75
    before_all: str
76
    before_build: str
77
    repair_wheel_command: str | None
78
    test_command: str
79
    test_requires: list[str]
80
    test_extras: str
81
    config_settings: dict[str, str | list[str]]
82
    # ... many more build-specific options
83
```
84

85
### Command Line Arguments
86

87
Parsed command-line arguments structure.
88

89
```python { .api }
90
@dataclasses.dataclass(kw_only=True)
91
class CommandLineArguments:
92
    platform: Literal["auto", "linux", "macos", "windows"] | None
93
    archs: str | None
94
    output_dir: Path
95
    only: str | None
96
    config_file: str
97
    package_dir: Path
98
    print_build_identifiers: bool
99
    allow_empty: bool
100
    debug_traceback: bool
101
    enable: list[str]
102
    clean_cache: bool
103
```
104

105
### Options Computation
106

107
Main function for computing final options from all sources.
108

109
```python { .api }
110
def compute_options(
111
    platform: PlatformName, 
112
    command_line_arguments: CommandLineArguments, 
113
    env: Mapping[str, str]
114
) -> Options:
115
    """
116
    Compute final build options from all configuration sources.
117
    
118
    Args:
119
        platform: Target platform name
120
        command_line_arguments: Parsed CLI arguments
121
        env: Environment variables
122
        
123
    Returns:
124
        Complete Options object with resolved configuration
125
        
126
    Raises:
127
        ConfigurationError: If configuration is invalid or conflicting
128
    """
129
```
130

131
### Build Frontend Configuration
132

133
Configuration for the tool used to build wheels.
134

135
```python { .api }
136
BuildFrontendName = Literal["pip", "build", "build[uv]"]
137

138
@dataclasses.dataclass(frozen=True)
139
class BuildFrontendConfig:
140
    name: BuildFrontendName
141
    args: Sequence[str] = ()
142
```
143

144
## Configuration Sources
145

146
### TOML Configuration Files
147

148
Primary configuration method using `pyproject.toml` or dedicated config files:
149

150
```toml
151
[tool.cibuildwheel]
152
# Build selection
153
build = "cp39-* cp310-* cp311-*"
154
skip = "*-win32 *-linux_i686"
155

156
# Build customization  
157
build-frontend = "build"
158
config-settings = {cmake.define.BUILD_TESTING = "OFF"}
159

160
# Environment variables
161
environment = {CFLAGS = "-O2", LDFLAGS = "-s"}
162

163
# Testing
164
test-command = "pytest {project}/tests"
165
test-requires = ["pytest", "numpy"]
166

167
# Platform-specific overrides
168
[tool.cibuildwheel.linux]
169
before-all = "yum install -y cmake"
170
manylinux-x86_64-image = "manylinux2014"
171

172
[tool.cibuildwheel.windows]
173
before-build = "pip install delvewheel"
174

175
[tool.cibuildwheel.macos]
176
archs = ["universal2"]
177
```
178

179
### Environment Variables
180

181
Configuration via environment variables with `CIBW_` prefix:
182

183
```bash
184
# Build selection
185
export CIBW_BUILD="cp39-* cp310-* cp311-*"
186
export CIBW_SKIP="*-win32 *-linux_i686"
187

188
# Build customization
189
export CIBW_BUILD_FRONTEND="build"
190
export CIBW_ENVIRONMENT="CFLAGS=-O2 LDFLAGS=-s"
191

192
# Testing  
193
export CIBW_TEST_COMMAND="pytest {project}/tests"
194
export CIBW_TEST_REQUIRES="pytest numpy"
195

196
# Platform-specific (Linux example)
197
export CIBW_BEFORE_ALL_LINUX="yum install -y cmake"
198
export CIBW_MANYLINUX_X86_64_IMAGE="manylinux2014"
199
```
200

201
### Command Line Options
202

203
Override configuration via command-line arguments:
204

205
```bash
206
cibuildwheel \
207
  --platform linux \
208
  --archs x86_64,aarch64 \
209
  --output-dir wheelhouse \
210
  --config-file custom-build.toml
211
```
212

213
## Configuration Hierarchy
214

215
Configuration sources are merged in this priority order (highest to lowest):
216

217
1. **Command-line arguments**
218
2. **Environment variables** 
219
3. **TOML configuration files**
220
4. **Default values**
221

222
### Platform-Specific Overrides
223

224
Platform-specific settings override global settings:
225

226
```toml
227
[tool.cibuildwheel]
228
# Global setting
229
build = "cp39-* cp310-* cp311-*"
230

231
[tool.cibuildwheel.linux]  
232
# Linux override - adds cp312
233
build = "cp39-* cp310-* cp311-* cp312-*"
234

235
[tool.cibuildwheel.windows]
236
# Windows override - removes cp39
237
build = "cp310-* cp311-*"
238
```
239

240
## Key Configuration Options
241

242
### Build Selection
243

244
```toml
245
[tool.cibuildwheel]
246
# Python versions to build
247
build = "cp39-* cp310-* cp311-*"
248

249
# Python versions/platforms to skip
250
skip = ["*-win32", "*-linux_i686", "pp*"]
251

252
# Enable additional build categories
253
enable = ["pypy", "graalpy"]
254

255
# Allow empty build selection
256
allow-empty = true
257

258
# Project's Python compatibility
259
project-requires-python = ">=3.9"
260
```
261

262
### Build Customization
263

264
```toml
265
[tool.cibuildwheel]
266
# Build tool selection
267
build-frontend = {name = "build", args = ["--installer", "uv"]}
268

269
# Build backend config settings
270
config-settings = "cmake.define.BUILD_TESTING=OFF"
271

272
# Environment variables for builds
273
environment = {CFLAGS = "-O2", LDFLAGS = "-s"}
274

275
# Environment variables to pass from host
276
environment-pass = ["SECRET_TOKEN", "API_KEY"]
277

278
# Commands to run before builds
279
before-all = "yum install -y cmake"
280
before-build = "pip install cython"
281

282
# Custom wheel repair command
283
repair-wheel-command = "auditwheel repair -w {dest_dir} {wheel}"
284
```
285

286
### Testing Configuration
287

288
```toml
289
[tool.cibuildwheel]
290
# Test command template
291
test-command = "pytest {project}/tests"
292

293
# Test dependencies
294
test-requires = ["pytest", "numpy", "scipy"]
295

296
# Test extras (optional dependencies)
297
test-extras = ["test", "docs"]
298

299
# Skip tests for certain builds
300
test-skip = ["*-linux_ppc64le", "*-linux_s390x"]
301
```
302

303
### Container Configuration (Linux)
304

305
```toml
306
[tool.cibuildwheel.linux]
307
# Custom container images
308
manylinux-x86_64-image = "quay.io/pypa/manylinux2014_x86_64"
309
musllinux-x86_64-image = "quay.io/pypa/musllinux_1_1_x86_64"
310

311
# Container engine selection
312
container-engine = "docker"  # or "podman"
313
```
314

315
## Schema Validation
316

317
### Schema Access
318

319
Access the JSON schema for configuration validation.
320

321
```python { .api }
322
def get_schema(tool_name: str = "cibuildwheel") -> dict[str, Any]:
323
    """
324
    Get the JSON schema for cibuildwheel configuration.
325
    
326
    Args:
327
        tool_name: Name of the tool section in pyproject.toml
328
        
329
    Returns:
330
        JSON schema dictionary for validation
331
    """
332
```
333

334
### PyProject.toml Integration
335

336
Cibuildwheel provides a schema entry point for `validate-pyproject`:
337

338
```python
339
# Entry point: validate_pyproject.tool_schema
340
"cibuildwheel" = "cibuildwheel.schema:get_schema"
341
```
342

343
### IDE Integration
344

345
Many IDEs can use the schema for autocomplete and validation:
346

347
```json
348
{
349
  "$schema": "https://json.schemastore.org/pyproject.json",
350
  "tool": {
351
    "cibuildwheel": {
352
      "build": "cp39-* cp310-* cp311-*"
353
    }
354
  }
355
}
356
```
357

358
## Advanced Configuration
359

360
### Dynamic Configuration
361

362
```python
363
# Use environment variables for dynamic config
364
import os
365
import sys
366

367
# Conditional builds based on CI environment
368
if os.environ.get("CI_QUICK_BUILD"):
369
    CIBW_BUILD = f"cp{sys.version_info.major}{sys.version_info.minor}-*"
370
else:
371
    CIBW_BUILD = "cp39-* cp310-* cp311-*"
372
```
373

374
### Multi-Stage Configuration
375

376
```toml
377
[tool.cibuildwheel]
378
# Base configuration
379
build = "cp39-* cp310-* cp311-*"
380
test-command = "pytest"
381

382
# Development profile
383
[tool.cibuildwheel.dev]
384
build = "cp311-*"  # Only current version
385
test-skip = "*"    # Skip tests
386
archs = "native"   # Native arch only
387

388
# Release profile  
389
[tool.cibuildwheel.release]
390
build = "*"        # All versions
391
enable = ["pypy"]  # Include PyPy
392
test-command = "pytest --cov"
393
```
394

395
### Configuration Validation
396

397
```python
398
from cibuildwheel.options import compute_options, CommandLineArguments
399
from cibuildwheel.errors import ConfigurationError
400

401
try:
402
    options = compute_options(
403
        platform="linux",
404
        command_line_arguments=args,
405
        env=os.environ
406
    )
407
    # Configuration is valid
408
except ConfigurationError as e:
409
    print(f"Configuration error: {e}")
410
```
411

412
## Configuration Examples
413

414
### Minimal Configuration
415

416
```toml
417
[tool.cibuildwheel]
418
build = "cp311-*"
419
test-command = "python -m pytest"
420
```
421

422
### Full-Featured Configuration
423

424
```toml
425
[tool.cibuildwheel]
426
# Build all recent Python versions
427
build = "cp39-* cp310-* cp311-* cp312-*"
428
skip = ["*-win32", "*-linux_i686"]  # Skip 32-bit
429
enable = ["pypy"]
430

431
# Build customization
432
build-frontend = "build"
433
environment = {CFLAGS = "-O2"}
434
before-build = "pip install cython numpy"
435

436
# Testing
437
test-command = "pytest {project}/tests -x -v"
438
test-requires = ["pytest", "pytest-xdist"]
439
test-extras = ["test"]
440

441
# Platform overrides
442
[tool.cibuildwheel.linux]
443
before-all = "yum install -y cmake gcc-c++"
444
manylinux-x86_64-image = "manylinux2014"
445

446
[tool.cibuildwheel.macos]
447
archs = ["universal2"]
448
environment = {MACOSX_DEPLOYMENT_TARGET = "10.14"}
449

450
[tool.cibuildwheel.windows]
451
before-build = "pip install delvewheel"
452
```