Skip to content

[BLD] Add win_arm64 wheel build to CI#7447

Draft
vortex-captain wants to merge 2 commits into
chroma-core:mainfrom
vortex-captain:win-arm64-ci
Draft

[BLD] Add win_arm64 wheel build to CI#7447
vortex-captain wants to merge 2 commits into
chroma-core:mainfrom
vortex-captain:win-arm64-ci

Conversation

@vortex-captain

@vortex-captain vortex-captain commented Jul 16, 2026

Copy link
Copy Markdown

Summary

Adds a Windows ARM64 (aarch64-pc-windows-msvc) wheel build leg to the PyPI
release workflow, mirroring the existing win_amd64 build as closely as
possible.

The wheel is cp39-abi3-win_arm64 (from pyo3 abi3-py39), matching the abi3
tag produced on every other platform.

Changes

  • .github/workflows/_build_release_pypi.yml — add
    { os: windows, runner: windows-11-arm, target: aarch64 } to the build matrix,
    plus a step to put the VS-bundled ARM64 clang on PATH and set
    CFLAGS/CXXFLAGS_aarch64_pc_windows_msvc=-D_ARM64_=1 for the arm64 leg only.
  • .github/actions/python/action.yaml — skip the x64 SQLite-DLL upgrade on
    ARM64 (the x64 DLL is ABI-incompatible; arm64 Python already ships sqlite ≥ 3.35).
  • Cargo.lock — bump generator 0.8.8 → 0.8.9 (adds aarch64_windows.rs,
    required for aarch64-pc-windows-msvc).

Native-toolchain notes (not feature changes)

Feature enablement is identical to win_amd64/linux aarch64 — same
[tool.maturin] features, abi3-py39, no --zig (Linux-only). The arm64 leg
only needed build-toolchain fixes:

  • ring requires clang on aarch64-pc-windows-msvc.
  • simsimd (bundled directly and via usearch) includes <processthreadsapi.h>
    on Windows-ARM, which needs the _ARM64_ SDK arch macro. It is compiled as C
    (CFLAGS) directly and as C++ by usearch (CXXFLAGS), so both are set.
  • The x64 sqlite DLL hack is a runner workaround, not a wheel feature, and is
    skipped on arm64.

Build validation ✅

The build leg was validated on a GitHub-hosted windows-11-arm runner and
succeeded, producing chromadb-*-cp39-abi3-win_arm64.whl (~22.7 MB).

Why no win_arm64 test job is added

No aarch64 target is currently tested in CI on any OSlinux aarch64 and
both macOS arches (x86_64 and aarch64) are already built-and-published without a
test job; only linux x86_64 and windows x64 run the test suite. This PR keeps
win_arm64 consistent with that existing policy: it builds and publishes the
wheel (same as linux aarch64 / macOS) but does not add a test job.

Adding a win_arm64 test job would also currently be blocked by external ecosystem
gaps — dependencies with no win_arm64 wheels on PyPI:

Dependency Role Impact
grpcio Runtime dep of chromadb (direct in pyproject.toml, and transitive via opentelemetry-exporter-otlp-proto-grpc) No PyPI win_arm64 wheel ⇒ pip install chromadb cannot resolve on arm64 without an external arm64 wheel source.
grpcio-tools Build-time proto stub generator (used by .github/actions/python) No PyPI win_arm64 wheel. Not required to run tests (stubs ship inside the wheel), but the proto-gen step would need adjusting for arm64.
pulsar-client (via legacy chromadb==0.4.1) Only used by test_cross_version_persist.py No win_arm64 wheel ⇒ the cross-version persistence test cannot install old chromadb releases.

Local test results (win_arm64, all win_amd64-equivalent jobs)

Even though no CI test job is added, the wheel was validated locally on a native
Windows ARM64 host against the built cp39-abi3-win_arm64 wheel
(grpcio/grpcio-tools supplied from prebuilt arm64 wheels; chroma-hnswlib
built from source), using the exact CI targets and env
(CHROMA_RUST_BINDINGS_TEST_ONLY=1, PROPERTY_TESTING_PRESET=normal):

CI job / target Result
test-rust-bindings — core 778 passed, 152 skipped, 1 xfailed
test-rust-bindings — property 98 passed, 12 skipped, 2 xfailed, 2 xpassed
test-rust-bindings-stress 2 passed
test-python-cli 3 passed
test-rust-single-node-integration — core 767 passed, 164 skipped, 1 xfailed
test-rust-single-node-integration — property 71 passed, 7 skipped, 2 xpassed
test-rust-single-node-integration — stress 2 passed
test-rust-thin-client 74 passed, 13 skipped, 1 xfailed, 2 xpassed
test-rust-bindings — cross-version ⛔ blocked (pulsar-client has no win_arm64 wheel)

test-cluster-rust-frontend is ubuntu-only and not part of the Windows path.

Note: this leg publishes to PyPI

Adding the windows/aarch64 entry to the build matrix means its artifact is
swept up by the release job's download-artifact + maturin upload wheels-*/*
and published to PyPI on release (Test PyPI on main, real PyPI on a version
tag) — the intended outcome, and consistent with the already-published-untested
linux aarch64 / macOS wheels.

Notes for reviewers

  • The commit [BLD] TMP: win_arm64 build-only validation workflow adds a
    temporary workflow_dispatch workflow used only to validate the build on a
    hosted arm64 runner. It should be dropped before merge.

@github-actions

Copy link
Copy Markdown

Reviewer Checklist

Please leverage this checklist to ensure your code review is thorough before approving

Testing, Bugs, Errors, Logs, Documentation

  • Can you think of any use case in which the code does not behave as intended? Have they been tested?
  • Can you think of any inputs or external events that could break the code? Is user input validated and safe? Have they been tested?
  • If appropriate, are there adequate property based tests?
  • If appropriate, are there adequate unit tests?
  • Should any logging, debugging, tracing information be added or removed?
  • Are error messages user-friendly?
  • Have all documentation changes needed been made?
  • Have all non-obvious changes been commented?

System Compatibility

  • Are there any potential impacts on other parts of the system or backward compatibility?
  • Does this change intersect with any items on our roadmap, and if so, is there a plan for fitting them together?

Quality

  • Is this code of a unexpectedly high quality (Readability, Modularity, Intuitiveness)

Yi Ren added 2 commits July 16, 2026 14:58
Add an aarch64-pc-windows-msvc build leg to the PyPI wheel workflow,
mirroring the win_amd64 build. No test job is added, matching how
linux aarch64 and macOS wheels are already built without CI tests.

Native-toolchain requirements handled (not feature changes):
- clang on PATH for ring
- CFLAGS/CXXFLAGS _ARM64_=1 for simsimd/usearch on Windows-ARM
- generator 0.8.9 (adds aarch64_windows.rs)
- skip the x64 sqlite DLL upgrade on ARM64
Temporary workflow_dispatch workflow to validate the Windows ARM64 wheel
build on a GitHub-hosted windows-11-arm runner, with tests skipped. Delete
before merging.
@vortex-captain vortex-captain changed the title [BLD] Add win_arm64 wheel build to CI (tests temporarily skipped) [BLD] Add win_arm64 wheel build to CI Jul 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant