Native wheels do not travel

Wheels with native extensions are compiled for a specific operating system and processor architecture. Install them on the machine you are sitting at, ship them to a Linux runtime, and the failure arrives at cold start rather than at build time.

The symptom

Runtime.ImportModuleError: Unable to import module 'handler':
No module named 'pydantic_core._pydantic_core'

The module is right there in the bundle. What is missing is a build of it for the architecture the code is running on. A macOS wheel ships a Mach-O object; an arm64 Linux runtime needs an ELF one.

The fix

Pin the target explicitly rather than letting pip resolve for the host:

pip install -r requirements.txt -t build \
  --platform manylinux2014_aarch64 \
  --implementation cp --python-version 3.12 \
  --only-binary=:all:

--only-binary=:all: matters as much as the platform flag. Without it pip will happily fall back to building from source, on your machine, for your machine.

Check it in CI

You cannot import the bundle to test it, because the runner is a different architecture. You can read the binaries:

head = so.read_bytes()[:20]
assert head[:4] == b"\\x7fELF", f"{so}: not an ELF object"
assert struct.unpack_from("<H", head, 18)[0] == 0xB7, f"{so}: not AArch64"

Fast, exact, and it fails in the build rather than in front of a user.