0
# Command Line Interface
1
2
Cibuildwheel provides a comprehensive command-line interface for building Python wheels across multiple platforms and architectures.
3
4
## Capabilities
5
6
### Main Command
7
8
The primary entry point for cibuildwheel operations.
9
10
```python { .api }
11
def main() -> None:
12
"""
13
Main CLI entry point for cibuildwheel.
14
15
Parses command line arguments, validates configuration,
16
and orchestrates the wheel building process.
17
18
Raises:
19
FatalError: On configuration errors or build failures
20
"""
21
22
def main_inner(global_options: GlobalOptions) -> None:
23
"""
24
Internal main function that performs the actual build logic.
25
26
Same as main() but raises FatalError exceptions rather than
27
exiting directly, allowing for custom error handling.
28
29
Args:
30
global_options: Global build options and configuration
31
32
Raises:
33
FatalError: On configuration errors or build failures
34
"""
35
```
36
37
### Command Line Arguments
38
39
#### Platform Selection
40
41
```bash
42
cibuildwheel --platform <platform>
43
```
44
45
Choose the target platform for wheel building:
46
- `auto` (default): Auto-detect current platform
47
- `linux`: Build for Linux using containers
48
- `macos`: Build for macOS (requires macOS runner)
49
- `windows`: Build for Windows (requires Windows runner)
50
- `pyodide`: Build for Pyodide WebAssembly
51
- `android`: Build for Android
52
- `ios`: Build for iOS (requires macOS runner)
53
54
#### Architecture Selection
55
56
```bash
57
cibuildwheel --archs <architectures>
58
```
59
60
Specify target CPU architectures (comma-separated):
61
- `auto` (default): Build for architectures natively supported
62
- `native`: Build only for the current machine's architecture
63
- `all`: Build for all supported architectures on the platform
64
- `auto64`: Build for 64-bit architectures only
65
- `auto32`: Build for 32-bit architectures only
66
- Specific architectures: `x86_64,aarch64,arm64,i686,etc.`
67
68
#### Build Selection
69
70
```bash
71
cibuildwheel --only <identifier>
72
```
73
74
Force building a single wheel by its build identifier (e.g., `cp311-linux_x86_64`). This overrides `CIBW_BUILD`/`CIBW_SKIP` settings.
75
76
```bash
77
cibuildwheel --enable <group>
78
```
79
80
Enable additional categories of builds (can be used multiple times):
81
- `cpython-prerelease`: Include CPython prerelease versions
82
- `pypy`: Include PyPy builds
83
- `graalpy`: Include GraalPy builds
84
- `cpython-freethreading`: Include free-threaded CPython
85
86
#### Output Configuration
87
88
```bash
89
cibuildwheel --output-dir <directory>
90
```
91
92
Specify destination folder for built wheels (default: `wheelhouse`).
93
94
#### Configuration
95
96
```bash
97
cibuildwheel --config-file <path>
98
```
99
100
Specify TOML configuration file path. Default is `{package}/pyproject.toml` if it exists.
101
102
#### Package Source
103
104
```bash
105
cibuildwheel [PACKAGE]
106
```
107
108
Path to the package directory or SDist file. Default is the current working directory.
109
110
#### Utility Options
111
112
```bash
113
cibuildwheel --print-build-identifiers
114
```
115
116
Print the build identifiers that match the current configuration and exit without building.
117
118
```bash
119
cibuildwheel --clean-cache
120
```
121
122
Clear the cibuildwheel cache directory and exit.
123
124
```bash
125
cibuildwheel --allow-empty
126
```
127
128
Don't report an error if no wheels match the build selection criteria.
129
130
```bash
131
cibuildwheel --debug-traceback
132
```
133
134
Print full Python tracebacks for all errors (useful for debugging).
135
136
## Usage Examples
137
138
### Basic Usage
139
140
```bash
141
# Build wheels for current platform
142
cibuildwheel
143
144
# Build for specific platform
145
cibuildwheel --platform linux
146
147
# Build specific Python versions only
148
cibuildwheel --only cp311-linux_x86_64
149
```
150
151
### Cross-Platform Building
152
153
```bash
154
# Build for multiple architectures
155
cibuildwheel --archs x86_64,aarch64
156
157
# Build for all 64-bit architectures
158
cibuildwheel --archs auto64
159
160
# Build for Linux with emulation
161
cibuildwheel --platform linux --archs x86_64,aarch64,ppc64le
162
```
163
164
### Advanced Configuration
165
166
```bash
167
# Use custom config file
168
cibuildwheel --config-file custom-build.toml
169
170
# Custom output directory
171
cibuildwheel --output-dir dist/wheels
172
173
# Enable prerelease Python versions
174
cibuildwheel --enable cpython-prerelease
175
176
# Debug mode with full tracebacks
177
cibuildwheel --debug-traceback
178
```
179
180
### CI Integration
181
182
```bash
183
# GitHub Actions matrix build
184
cibuildwheel --platform ${{ matrix.platform }} --output-dir wheelhouse
185
186
# Build from SDist
187
cibuildwheel package-1.0.0.tar.gz --output-dir wheels
188
```
189
190
### Inspection and Debugging
191
192
```bash
193
# See what would be built
194
cibuildwheel --print-build-identifiers
195
196
# Clean cache if needed
197
cibuildwheel --clean-cache
198
199
# Allow empty builds (useful for conditional CI)
200
cibuildwheel --allow-empty
201
```
202
203
## Return Codes
204
205
The cibuildwheel command returns specific exit codes for different error conditions:
206
207
- `0`: Success
208
- `1`: General fatal error
209
- `2`: Configuration error
210
- `3`: No builds matched selection criteria
211
- `4`: Deprecated configuration detected
212
- `5`: Non-platform wheel detected
213
- `6`: Wheel already exists (when configured to fail)
214
- `7`: Container engine too old
215
- `8`: Wheel repair step failed
216
217
## Environment Variables
218
219
Many CLI options can also be controlled via environment variables with the `CIBW_` prefix:
220
221
- `CIBW_PLATFORM`: Equivalent to `--platform`
222
- `CIBW_ARCHS`: Equivalent to `--archs`
223
- `CIBW_OUTPUT_DIR`: Equivalent to `--output-dir`
224
- `CIBW_CONFIG_FILE`: Equivalent to `--config-file`
225
- `CIBW_DEBUG_TRACEBACK`: Equivalent to `--debug-traceback`
226
227
Plus many more configuration options for fine-tuning the build process.