cibuildwheel Python Wheels: Build Cho Mọi CI
cibuildwheel là công cụ command-line của PyPA để build và test Python wheels cho macOS, Windows, và Linux ngay trong pipeline CI của bạn. Nó giao bước repair cho auditwheel, delocate, hoặc delvewheel tuỳ nền tảng, nên một file config thay thế các script build riêng cho từng OS. Hãy dùng nó ngay khi package của bạn có C extension và cần wheel cho nhiều nền tảng; bỏ qua nếu project của bạn là pure Python, vì một sdist thông thường đã đủ.
Thách Thức Build Python Wheels Đa Nền Tảng
Người maintain package Python có C extension không thể chỉ chạy `pip install` là xong — mỗi kết hợp OS, kiến trúc, và phiên bản CPython/PyPy/GraalPy cần một wheel compiled riêng, build trong container với đúng compiler toolchain, rồi repair lại để nó không âm thầm phụ thuộc vào một shared library chỉ tồn tại trên máy build. Trước cibuildwheel, điều đó có nghĩa là tự viết script build riêng cho từng CI provider và tự nối dây manylinux container, delocate, delvewheel. README của cibuildwheel đóng khung lý do tồn tại của nó đúng quanh vấn đề đó: một lệnh duy nhất điều khiển tool repair theo từng nền tảng và ma trận Python mục tiêu cho bạn.
cibuildwheel Tự Động Hoá Những Gì
cibuildwheel tự động build và test Python wheels trên mọi nền tảng mà package của bạn cần ship, chạy từ bên trong một job CI thay vì trên laptop. Nó chạy `python -m cibuildwheel --output-dir wheelhouse`, tự phát hiện nền tảng mục tiêu, build với các phiên bản CPython, PyPy, hoặc GraalPy bạn chọn, repair từng wheel bằng auditwheel (Linux), delocate (macOS), hoặc delvewheel (Windows), rồi cài lại wheel đã repair và chạy lệnh test của bạn trên đó.
Hỗ Trợ Toàn Diện Nền Tảng Và Python
- ✓Nhắm tới CPython 3.9 đến 3.15, PyPy 3.9-3.11 v7.3, và GraalPy 3.12 v25.0, theo bảng hỗ trợ phiên bản trong README — build PyPy và GraalPy chỉ giới hạn ở manylinux wheels.
- ✓Build manylinux và musllinux wheels cho x86_64, i686, aarch64, ppc64le, và s390x, cộng thêm target armv7l mà README đánh dấu là experimental (chạy trên image nền Ubuntu vì không có image nền RHEL cho kiến trúc này).
- ✓Bao phủ macOS Intel và Apple Silicon, cộng Windows 64-bit, 32-bit, và target Windows ARM64 experimental được build qua cross-compilation — README nói arm64 không thể test được trên runner CI của Windows.
- ✓Cũng build wheel cho Pyodide (WebAssembly), và — bắt đầu từ CPython 3.13 — wheel cho Android và iOS, theo bảng hỗ trợ.
- ✓Repair shared library dependencies theo từng nền tảng: auditwheel trên Linux, delocate trên macOS, delvewheel trên Windows, bundle những gì mỗi wheel cần để chạy được mà không cần thêm bước cài đặt.
- ✓Cài lại wheel vừa build và chạy lệnh test của chính project trên đó, thay vì chỉ kiểm tra build không lỗi.
- ✓Chạy trên GitHub Actions, Azure Pipelines, CircleCI, và GitLab CI, với config đặt trong pyproject.toml hoặc dưới dạng biến môi trường — cùng một config chạy được trên mọi provider.
- ✓Các option bao gồm chọn build (platform, archs, enable), tuỳ biến build (before-build, repair-wheel-command, container-engine), và kiểm soát test (test-command, test-requires, test-skip), theo bảng option trong README.
Tích Hợp Vào CI Workflow Của Bạn
Ví dụ trong README cài một phiên bản pin bằng `python -m pip install cibuildwheel==4.2.0`, rồi chạy `python -m cibuildwheel --output-dir wheelhouse` như một bước CI — không cần cài local, vì cibuildwheel được thiết kế để chạy ngay trong job CI. File `.github/workflows/wheels.yml` mẫu trong README build trên ma trận runner `ubuntu-latest`, `ubuntu-24.04-arm`, `windows-latest`, `windows-11-arm`, `macos-15-intel`, và `macos-latest`, dùng `actions/setup-python` để host cibuildwheel và `actions/upload-artifact` để thu các file `.whl` đã build từ thư mục `wheelhouse`. README cũng trỏ tới một GitHub Action riêng và hướng dẫn setup cho từng provider — Azure Pipelines, CircleCI, GitLab CI — trong tài liệu đầy đủ, dù không liệt kê chi tiết ngay trong README.
Tuỳ Biến Quá Trình Build Wheel
Mọi option đều đặt được trong `pyproject.toml` hoặc dưới dạng biến môi trường, đó chính là các biến prefix `CIBW_` xuất hiện trong hầu hết ví dụ. Các option chọn build như `platform`, `archs`, và `build`/`skip` thu hẹp những wheel thực sự được build; `enable` bật thêm các nhóm selector khác như CPython prerelease. Tuỳ biến build chạy shell command tại các thời điểm xác định — `before-all` chạy một lần cho mỗi nền tảng trước khi build wheel nào, `before-build` chạy trước từng wheel riêng lẻ, và `repair-wheel-command` ghi đè hoàn toàn bước repair mặc định auditwheel/delocate/delvewheel nếu bạn cần một tool repair khác. Các option test tách riêng: `test-command` chạy trên wheel đã cài, `test-requires` và `test-extras` kéo thêm dependency cho test, và `test-skip` loại một số build identifier khỏi việc test, tất cả đều nằm trong bảng option của README.
Các Project Đang Dùng cibuildwheel
- •Build wheel với Cython và C++ extension ở quy mô lớn — README nêu config cibuildwheel của scikit-learn là ví dụ 'phức tạp nhưng gọn gàng' cho việc này.
- •Ship package Python compiled cho công cụ dữ liệu: README liệt kê DuckDB, một hệ quản trị cơ sở dữ liệu SQL in-process phân tích, và NumPy là các project dùng cibuildwheel.
- •Compile bằng mypyc thay vì Python thuần — README nêu bản build wheel compiled bằng mypyc của chính MyPy làm ví dụ.
- •Chạy build wheel trên self-hosted runner: README liệt kê Triton làm đúng điều đó với cibuildwheel.
- •Build các thư viện nặng C-extension như bộ công cụ fairseq của Facebook AI Research và thư viện dự báo Prophet, cả hai đều được nêu trong bảng working-examples của README.
Điểm Mạnh
- ✓Một config điều khiển bốn CI provider — GitHub Actions, Azure Pipelines, CircleCI, và GitLab CI — đặt qua cùng các option pyproject.toml hoặc biến môi trường, theo README.
- ✓Bao phủ ma trận nền tảng rộng bất thường cho một công cụ: manylinux/musllinux trên năm kiến trúc, macOS Intel và Apple Silicon, Windows kể cả ARM64, Pyodide, Android, và iOS.
- ✓Tự xử lý bước repair — auditwheel, delocate, hoặc delvewheel — thay vì để bạn tự nối dây từng tool theo từng nền tảng.
- ✓Test đúng wheel đã build và cài, không chỉ source checkout, bắt được lỗi đóng gói mà unit test chạy trên repo sẽ bỏ sót.
- ✓Có adopter thực tế được nêu trong README — scikit-learn, NumPy, DuckDB, Matplotlib, và MyPy trong số đó — trải rộng nhiều mức độ phức tạp build.
- ✓License BSD-2-Clause, và config nằm trong pyproject.toml cùng phần metadata đóng gói còn lại thay vì một định dạng riêng độc quyền.
Lưu Ý Và Cảnh Báo Quan Trọng
- △Build và test wheel thực thi code tuỳ ý từ project và dependency của nó; cảnh báo trong chính README nói OCI container và Pyodide không đảm bảo bảo mật, nên khuyến nghị tách job build khỏi job upload lên PyPI và xử lý credential cẩn thận.
- △Wheel sau khi repair có thể bundle các dynamically linked library từ máy build — ghi chú pháp lý trong README so sánh điều này với static linking và nói nó 'có thể có ảnh hưởng về license,' nên bạn cần kiểm tra license của những gì mình đang kéo vào.
- △Hỗ trợ Windows ARM64 được đánh dấu experimental và build qua cross-compilation; README nói arm64 không thể test được trên nền tảng CI đó.
- △Hỗ trợ manylinux armv7l cũng experimental — README ghi chú không có container image nền RHEL cho kiến trúc này, nên nó chạy trên image nền Ubuntu thay thế.
- △Hỗ trợ Linux ARM của GitLab CI cần emulation được phân phối riêng, và một số kết hợp CI-provider cho build Android, iOS, và Pyodide bị chính bảng hỗ trợ trong README đánh dấu là chưa được test trong CI của cibuildwheel dù có thể vẫn chạy được.
Các Công Cụ Build Python Wheel Khác
Câu Hỏi Thường Gặp
cibuildwheel chạy trên GitHub Actions, Azure Pipelines, CircleCI, và GitLab CI theo README, với cùng một config trong pyproject.toml hoặc biến môi trường chạy được trên cả bốn.
cibuildwheel build wheel cho CPython 3.9 đến 3.15, PyPy 3.9 đến 3.11 (v7.3), và GraalPy 3.12 (v25.0), dù build PyPy và GraalPy chỉ giới hạn ở manylinux wheels.
cibuildwheel nhắm tới macOS (Intel và Apple Silicon), Windows (64-bit, 32-bit, và ARM64 experimental), Linux manylinux/musllinux trên năm kiến trúc cộng armv7l experimental, Pyodide, Android, và iOS.
README của cibuildwheel nêu một điểm: vì các tool repair như delocate, auditwheel, và delvewheel có thể bundle dynamically linked library từ máy build, tương tự static linking, bạn nên kiểm tra license của code mình đang kéo vào.
cibuildwheel repair từng wheel bằng tool riêng theo nền tảng — auditwheel trên Linux, delocate trên macOS, delvewheel trên Windows — bundle shared library dependency để wheel chạy được mà không cần thêm bước cài đặt.
cibuildwheel cài từng wheel đã build và chạy lệnh test của project bạn trên đó, cấu hình qua các option test-command, test-requires, và test-skip trong README.
Ai nên dùng — và ai nên bỏ qua
Hãy thử cibuildwheel nếu bạn maintain một package Python có C, C++, Cython, hay Rust extension và cần wheel cho nhiều hơn một OS hoặc kiến trúc — ma trận CI và bước repair tự động thay thế những gì lẽ ra phải viết tay theo từng nền tảng. Bỏ qua nếu package của bạn là pure Python không có code compiled, vì một sdist thông thường hoặc một lệnh `pip wheel` đã đủ mà không cần ma trận nền tảng hay overhead container của cibuildwheel; nó cũng không phải công cụ để build một wheel đơn lẻ ở local ngoài CI.
Repo liên quan
cibuildwheel có đáng để bạn bỏ thời gian?
ChatGPT, Claude và Perplexity đều đọc được trang này. Hỏi thử xem họ nghĩ gì về cibuildwheel.
