You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<sup>¹ PyPy is only supported for manylinux wheels.</sup><br>
40
40
<sup>² Windows arm64 support is experimental.</sup><br>
41
-
<sup>³ Alpine 3.14 and very briefly 3.15's default python3 [was not able to load](https://github.com/pypa/cibuildwheel/issues/934) musllinux wheels. This has been fixed; please upgrade the python package if using Alpine from before the fix.</sup><br>
42
-
<sup>⁴ Cross-compilation not supported with PyPy - to build these wheels you need to run cibuildwheel on an Apple Silicon machine.</sup><br>
43
-
<sup>⁵ CPython 3.12 is built by default using Python RCs, starting with cibuildwheel 2.15.</sup><br>
44
41
45
42
- Builds manylinux, musllinux, macOS 10.9+, and Windows wheels for CPython and PyPy
46
43
- Works on GitHub Actions, Azure Pipelines, Travis CI, AppVeyor, CircleCI, GitLab CI, and Cirrus CI
@@ -56,18 +53,16 @@ Usage
56
53
57
54
|| Linux | macOS | Windows | Linux ARM | macOS ARM | Windows ARM |
<sup>¹ [Requires emulation](https://cibuildwheel.readthedocs.io/en/stable/faq/#emulation), distributed separately. Other services may also support Linux ARM through emulation or third-party build hosts, but these are not tested in our CI.</sup><br>
68
-
<sup>² [Uses cross-compilation](https://cibuildwheel.readthedocs.io/en/stable/faq/#universal2). It is not possible to test `arm64` and the `arm64` part of a `universal2` wheel on this CI platform.</sup><br>
69
-
<sup>³ [Uses cross-compilation](https://cibuildwheel.readthedocs.io/en/stable/faq/#universal2). Thanks to Rosetta 2 emulation, it is possible to test `x86_64` and both parts of a `universal2` wheel on this CI platform.</sup><br>
70
-
<sup>⁴ [Uses cross-compilation](https://cibuildwheel.readthedocs.io/en/stable/faq/#windows-arm64). It is not possible to test `arm64` on this CI platform.</sup>
65
+
<sup>² [Uses cross-compilation](https://cibuildwheel.readthedocs.io/en/stable/faq/#windows-arm64). It is not possible to test `arm64` on this CI platform.</sup>
Copy file name to clipboardexpand all lines: docs/faq.md
+11-28
Original file line number
Diff line number
Diff line change
@@ -20,11 +20,11 @@ Linux wheels are built in [`manylinux`/`musllinux` containers](https://github.co
20
20
21
21
### Building macOS wheels for Apple Silicon {: #apple-silicon}
22
22
23
-
`cibuildwheel` supports cross-compiling `universal2`and `arm64` wheels on `x86_64` runners.
23
+
`cibuildwheel` supports both native builds and cross-compiling between `arm64` (Apple Silicon) and `x86_64` (Intel) architectures, including the cross-compatible `universal2` format.
24
24
25
25
#### Overview of Mac architectures
26
26
27
-
With the introduction of Apple Silicon, you now have several choices for wheels for Python 3.8+:
27
+
You have several choices for wheels for Python 3.8+:
28
28
29
29
##### `x86_64`
30
30
@@ -68,43 +68,26 @@ Opinions vary on which of arch-specific or `universal2` wheels are best - some p
68
68
69
69
See [GitHub issue 1333](https://github.com/pypa/cibuildwheel/issues/1333) for more discussion.
70
70
71
-
#### How to cross-compile
71
+
#### How?
72
72
73
-
With the exception of Cirrus CI, macOS CI runners are still Intel-based, and Apple Silicon wheels are not built by default on Intel runners. However, cross-compilation can be enabled by adding extra archs to the [`CIBW_ARCHS_MACOS` option](options.md#archs) - e.g. `x86_64 arm64`. Cross-compilation is provided by the Xcode toolchain.
73
+
It's easiest to build `x86_64`wheels on `x86_64` runners, and `arm64` wheels on `arm64` runners.
74
74
75
-
!!! important
76
-
When cross-compiling on Intel, it is not possible to test `arm64` and the `arm64` part of a `universal2` wheel.
75
+
On GitHub Actions, `macos-14` runners are `arm64`, and `macos-13` runners are `x86_64`. So all you need to do is ensure both are in your build matrix.
77
76
78
-
`cibuildwheel` will raise a warning to notify you of this - these warnings be be silenced by skipping testing on these platforms: `CIBW_TEST_SKIP: "*_arm64 *_universal2:arm64"`.
77
+
#### Cross-compiling
79
78
80
-
!!! note
81
-
Your runner needs Xcode Command Line Tools 12.2 or later to build `universal2` or `arm64`.
79
+
If your CI provider doesn't offer arm64 runners yet, or you want to create `universal2`, you'll have to cross-compile. Cross-compilation can be enabled by adding extra archs to the [`CIBW_ARCHS_MACOS` option](options.md#archs) - e.g. `CIBW_ARCHS_MACOS="x86_64 universal2"`. Cross-compilation is provided by Xcode toolchain v12.2+.
80
+
81
+
Regarding testing,
82
82
83
-
Only CPython 3.8 and newer support `universal2` and `arm64` wheels.
83
+
- On an arm64 runner, it is possible to test x86_64 wheels and both parts of a universal2 wheel using Rosetta 2 emulation.
84
+
- On an x86_64 runner, arm64 code can be compiled but it can't be tested. `cibuildwheel` will raise a warning to notify you of this - these warnings can be silenced by skipping testing on these platforms: `CIBW_TEST_SKIP: "*_arm64 *_universal2:arm64"`.
84
85
85
86
!!! note
86
87
If your project uses **Poetry** as a build backend, cross-compiling on macOS [does not currently work](https://github.com/python-poetry/poetry/issues/7107). In some cases arm64 wheels can be built but their tags will be incorrect, with the platform tag showing `x86_64` instead of `arm64`.
87
88
88
89
As a workaround, the tag can be fixed before running delocate to repair the wheel. The [`wheel tags`](https://wheel.readthedocs.io/en/stable/reference/wheel_tags.html) command is ideal for this. See [this workflow](https://gist.github.com/anderssonjohan/49f07e33fc5cb2420515a8ac76dc0c95#file-build-pendulum-wheels-yml-L39-L53) for an example usage of `wheel tags`.
89
90
90
-
Hopefully, cross-compilation is a temporary situation. Once we have widely available Apple Silicon CI runners, we can build `arm64` wheels natively. Until then, cross-compiling `arm64` or `universal2` wheels requires opt-in by setting `CIBW_ARCHS_MACOS` on Intel runners.
91
-
92
-
Here's an example GitHub Actions workflow with a job that builds for Apple Silicon:
93
-
94
-
> .github/workflows/build_macos.yml
95
-
96
-
```yml
97
-
{% include "../examples/github-apple-silicon.yml" %}
98
-
```
99
-
100
-
Here's an example Cirrus CI workflow with a job that builds for macOS Intel through Rosetta 2 emulation and for Apple Silicon natively:
101
-
102
-
> .cirrus.yml
103
-
104
-
```yml
105
-
{% include "../examples/cirrus-ci-intel-mac.yml" %}
106
-
```
107
-
108
91
### Building Linux wheels for non-native archs using emulation {: #emulation}
109
92
110
93
cibuildwheel supports building non-native architectures on Linux, via
0 commit comments