Package: cibuildwheel
cibuildwheelDocumentationPython wheels are great. Building them acrossMac, Linux, Windows, onmultiple versions of Python, is not.cibuildwheelis here to help.cibuildwheelruns on your CI server - currently it supports GitHub Actions, Azure Pipelines, Travis CI, AppVeyor, CircleCI, and GitLab CI - and it builds and tests your wheels across all of your platforms.What does it do?macOS IntelmacOS Apple SiliconWindows 64bitWindows 32bitWindows Arm64manylinuxmusllinux x86_64manylinuxmusllinux i686manylinuxmusllinux aarch64manylinuxmusllinux ppc64lemanylinuxmusllinux s390xCPython 3.6✅N/A✅✅N/A✅✅✅✅✅CPython 3.7✅N/A✅✅N/A✅✅✅✅✅CPython 3.8✅✅✅✅N/A✅✅✅✅✅CPython 3.9✅✅✅✅✅²✅³✅✅✅✅CPython 3.10✅✅✅✅✅²✅✅✅✅✅CPython 3.11✅✅✅✅✅²✅✅✅✅✅CPython 3.12⁵✅✅✅✅✅²✅✅✅✅✅PyPy 3.7 v7.3✅N/A✅N/AN/A✅¹✅¹✅¹N/AN/APyPy 3.8 v7.3✅✅⁴✅N/AN/A✅¹✅¹✅¹N/AN/APyPy 3.9 v7.3✅✅⁴✅N/AN/A✅¹✅¹✅¹N/AN/APyPy 3.10 v7.3✅✅⁴✅N/AN/A✅¹✅¹✅¹N/AN/A¹ PyPy is only supported for manylinux wheels.² Windows arm64 support is experimental.³ Alpine 3.14 and very briefly 3.15's default python3was not able to loadmusllinux wheels. This has been fixed; please upgrade the python package if using Alpine from before the fix.⁴ Cross-compilation not supported with PyPy - to build these wheels you need to run cibuildwheel on an Apple Silicon machine.⁵ CPython 3.12 is built by default using Python RCs, starting with cibuildwheel 2.15.Builds manylinux, musllinux, macOS 10.9+, and Windows wheels for CPython and PyPyWorks on GitHub Actions, Azure Pipelines, Travis CI, AppVeyor, CircleCI, GitLab CI, and Cirrus CIBundles shared library dependencies on Linux and macOS throughauditwheelanddelocateRuns your library's tests against the wheel-installed version of your librarySee thecibuildwheel 1 documentationif you need to build unsupported versions of Python, such as Python 2.Usagecibuildwheelruns inside a CI service. Supported platforms depend on which service you're using:LinuxmacOSWindowsLinux ARMmacOS ARMWindows ARMGitHub Actions✅✅✅✅¹✅²✅⁴Azure Pipelines✅✅✅✅²✅⁴Travis CI✅✅✅AppVeyor✅✅✅✅²✅⁴CircleCI✅✅✅✅²Gitlab CI✅✅✅¹Cirrus CI✅✅³✅✅✅¹Requires 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.²Uses cross-compilation. It is not possible to testarm64and thearm64part of auniversal2wheel on this CI platform.³Uses cross-compilation. Thanks to Rosetta 2 emulation, it is possible to testx86_64and both parts of auniversal2wheel on this CI platform.⁴Uses cross-compilation. It is not possible to testarm64on this CI platform.Example setupTo build manylinux, musllinux, macOS, and Windows wheels on GitHub Actions, you could use this.github/workflows/wheels.yml:name:Buildon:[push,pull_request]jobs:build_wheels:name:Build wheels on ${{ matrix.os }}runs-on:${{ matrix.os }}strategy:matrix:os:[ubuntu-20.04,windows-2019,macOS-11]steps:-uses:actions/checkout@v4# Used to host cibuildwheel-uses:actions/setup-python@v3-name:Install cibuildwheelrun:python -m pip install cibuildwheel==2.16.5-name:Build wheelsrun:python -m cibuildwheel --output-dir wheelhouse# to supply options, put them in 'env', like:# env:#   CIBW_SOME_OPTION: value-uses:actions/upload-artifact@v4with:name:cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}path:./wheelhouse/*.whlFor more information, including PyPI deployment, and the use of other CI services or the dedicated GitHub Action, check out thedocumentationand theexamples.How it worksThe following diagram summarises the steps that cibuildwheel takes on each platform.Explore an interactive version of this diagramin the docs.OptionsOptionDescriptionBuild selectionCIBW_PLATFORMOverride the auto-detected target platformCIBW_BUILDCIBW_SKIPChoose the Python versions to buildCIBW_ARCHSChange the architectures built on your machine by default.CIBW_PROJECT_REQUIRES_PYTHONManually set the Python compatibility of your projectCIBW_PRERELEASE_PYTHONSEnable building with pre-release versions of Python if availableBuild customizationCIBW_BUILD_FRONTENDSet the tool to use to build, either "pip" (default for now) or "build"CIBW_ENVIRONMENTSet environment variables needed during the buildCIBW_ENVIRONMENT_PASS_LINUXSet environment variables on the host to pass-through to the container during the build.CIBW_BEFORE_ALLExecute a shell command on the build system before any wheels are built.CIBW_BEFORE_BUILDExecute a shell command preparing each wheel's buildCIBW_REPAIR_WHEEL_COMMANDExecute a shell command to repair each built wheelCIBW_MANYLINUX_*_IMAGECIBW_MUSLLINUX_*_IMAGESpecify alternative manylinux / musllinux Docker imagesCIBW_CONTAINER_ENGINESpecify which container engine to use when building Linux wheelsCIBW_DEPENDENCY_VERSIONSSpecify how cibuildwheel controls the versions of the tools it usesTestingCIBW_TEST_COMMANDExecute a shell command to test each built wheelCIBW_BEFORE_TESTExecute a shell command before testing each wheelCIBW_TEST_REQUIRESInstall Python dependencies before running the testsCIBW_TEST_EXTRASInstall your wheel for testing using extras_requireCIBW_TEST_SKIPSkip running tests on some buildsOtherCIBW_BUILD_VERBOSITYIncrease/decrease the output of pip wheelThese options can be specified in a pyproject.toml file, as well; seeconfiguration.Working examplesHere are some repos that use cibuildwheel.NameCIOSNotesscikit-learnThe machine learning library. A complex but clean config using many of cibuildwheel's features to build a large project with Cython and C++ extensions.pytorch-fairseqFacebook AI Research Sequence-to-Sequence Toolkit written in Python.NumPyThe fundamental package for scientific computing with Python.TornadoTornado is a Python web framework and asynchronous networking library. Uses stable ABI for a small C extension.MatplotlibThe venerable Matplotlib, a Python library with C++ portionsNCNNncnn is a high-performance neural network inference framework optimized for the mobile platformProphetTool for producing high quality forecasts for time series data that has multiple seasonality with linear or non-linear growth.MyPyThe compiled version of MyPy using MyPyC.KivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOSduckdbDuckDB is an in-process SQL OLAP Database Management Systemℹ️ That's just a handful, there are many more! Check out theWorking Examplespage in the docs.Legal noteSincecibuildwheelrepairs the wheel withdelocateorauditwheel, it might automatically bundle dynamically linked libraries from the build machine.It helps ensure that the library can run without any dependencies outside of the pip toolchain.This is similar to static linking, so it might have some license implications. Check the license for any code you're pulling in to make sure that's allowed.Changelogv2.16.530 January 2024🐛 Fix an incompatibility with the GitHub Action and new GitHub Runner images for Windows that bundle Powershell 7.3+ (#1741)🛠 Preliminary support for newmacos-14arm64 runners (#1743)v2.16.428 January 2024🛠 Update manylinux pins to upgrade from a problematic PyPy version. (#1737)v2.16.326 January 2024🐛 Fix a bug when building from sdist, where relative paths to files in the package didn't work because the working directory was wrong (#1687)🛠 Adds the ability to disable mounting the host filesystem in containers to/host, through thedisable_host_mountsuboption onCIBW_CONTAINER_ENGINE.📚 A lot of docs improvements! (#1708, #1705, #1686, #1679, #1667, #1665)v2.16.23 October 2023🛠 Updates CPython 3.12 version to 3.12.0, final release (#1635)✨ Adds a debug optionCIBW_DEBUG_KEEP_CONTAINERto stop cibuildwheel deleting build containers after the build finishes. (#1620)📚 Adds support for[tool.cibuildwheel]checking by adding a schema compatible with thevalidate-pyprojecttool (#1622, #1628, #1629)🐛 Fix parsing ofCIBW_CONTAINER_ENGINEandCIBW_BUILD_FRONTENDoptions to not break arguments on:characters (#1621)🐛 Fix the evaluation order ofCIBW_ENVIRONMENTandCIBW_ENVIRONMENT_PASSso thatCIBW_ENVIRONMENTassignments can reference environment variables passed through from the host machine. (#1617)🛠 Supports manylinux images' deferred installation of interpreters through themanylinux-interpreterstool (#1630)v2.16.126 September 2023🛠 Updates the prerelease CPython 3.12 version to 3.12.0rc3 (#1625)🛠 Only callslinux32in containers when necessary (#1599)That's the last few versions.ℹ️Want more changelog? Head over tothe changelog page in the docs.ContributingFor more info on how to contribute to cibuildwheel, see thedocs.Everyone interacting with the cibuildwheel project via codebase, issue tracker, chat rooms, or otherwise is expected to follow thePSF Code of Conduct.MaintainersJoe Rickerby@joerickYannick Jadoul@YannickJadoulMatthieu Darbois@mayeutHenry Schreiner@henryiiiGrzegorz Bokota@CzakiCreditscibuildwheelstands on the shoulders of giants.⭐️ @matthew-brett formultibuildandmatthew-brett/delocate@PyPA for the manylinux Docker imagespypa/manylinux@ogrisel forwheelhouse-uploaderandrun_with_env.cmdMassive props also to-@zfrenchee forhelp debugging many issues@lelit for some great bug reports andcontributions@mayeut for aphenomenal PRpatching Python itself for better compatibility!@czaki for being a super-contributor over many PRs and helping out with countless issues!@mattip for his help with adding PyPy support to cibuildwheelSee alsoAnother very similar tool to consider ismatthew-brett/multibuild.multibuildis a shell script toolbox for building a wheel on various platforms. It is used as a basis to build some of the big data science tools, like SciPy.If you are building Rust wheels, you can get by without some of the tricks required to make GLIBC work via manylinux; this is especially relevant for cross-compiling, which is easy with Rust. Seematurin-actionfor a tool that is optimized for building Rust wheels and cross-compiling.