Validate Python Wheels on a Cloud Mac: Tags and Libraries

You’re working on a Python project on Windows and sending packages with native extensions to a cloud Mac for building. The logs show that the wheel was built successfully, but a colleague installs it and runs into an architecture mismatch or a missing dynamic library. The problem is usually not whether the archive can be created, but what it contains, where its dependencies point, and whether testing inadvertently relied on the source tree.

Starting with an existing project that includes pyproject.toml, this guide establishes three acceptance checks: tags, native libraries, and an isolated installation. It does not cover uploading to a package repository, nor does it treat a successful local test as proof of compatibility with every system.

1. Fix the Interpreter and Define the Validation Scope

Run the following commands from the project root on the remote Mac. Use an already installed Python version that meets the project’s requirements; don’t upgrade the interpreter in the middle of validation.

python3 -m venv .wheel-build
.wheel-build/bin/python -m pip --version
.wheel-build/bin/python -c \
'import platform, sys; print(sys.version); print(platform.machine()); print(sys.executable)'
sw_vers
xcodebuild -version

Save the output alongside the commit ID. The interpreter version, process architecture, and operating system version are all inputs to validation. An Apple Silicon machine does not necessarily mean that the current Python process is running as arm64.

Specify which Python version and minimum macOS version you intend to support, and whether the package includes native extensions. Even a pure Python package can depend on native packages, so checking only the top-level project is not enough.

The platform tag in a wheel filename is a compatibility claim, not a converter. Renaming an arm64 file to universal2 does not add another architecture to the binary.

2. Start with a Clearly Identified Build

First, make sure dist contains no packages left over from an earlier build, then build the file you intend to validate. Pin the build backend and its version using the project’s chosen constraint mechanism; default build isolation does not automatically lock all build dependencies.

mkdir -p dist
find dist -maxdepth 1 -name '*.whl' -print
.wheel-build/bin/python -m pip wheel \
  --no-deps --wheel-dir dist .

If the initial check lists old files, move them to a separate archive directory before proceeding. Do not mix them into this validation run. --no-deps only means that wheels will not be built for runtime dependencies; it does not prevent dependencies from being downloaded during the build.

The following check requires exactly one wheel in the directory and prints its internal metadata:

.wheel-build/bin/python - <<'PY'
from pathlib import Path
from zipfile import ZipFile

wheels = list(Path("dist").glob("*.whl"))
if len(wheels) != 1:
    raise SystemExit("Expected exactly one wheel")
wheel = wheels[0]
print(wheel.name)
with ZipFile(wheel) as archive:
    metadata = [
        name for name in archive.namelist()
        if name.endswith(".dist-info/WHEEL")
    ]
    if len(metadata) != 1:
        raise SystemExit("Invalid wheel metadata")
    print(archive.read(metadata[0]).decode("utf-8"))
PY

Check that the Tag values and the compatibility declared in the filename match your delivery target. py3-none-any is typically used for platform-independent packages. If the package contains native executables, review how it is packaged rather than simply trusting the tag.

3. Check Whether Native Libraries Depend on the Build Machine

Extract the wheel to a temporary directory and inspect its extension modules and dynamic libraries. The following code inspects files without running any programs from the package:

inspect_dir="$(mktemp -d)"
.wheel-build/bin/python - "$inspect_dir" <<'PY'
from pathlib import Path
from zipfile import ZipFile
import sys

wheel, = Path("dist").glob("*.whl")
with ZipFile(wheel) as archive:
    archive.extractall(sys.argv[1])
PY
find "$inspect_dir" -type f \
  \( -name '*.so' -o -name '*.dylib' \) \
  -exec file {} \; -exec otool -L {} \;

Use this extraction procedure for trusted artifacts from your own project. Do not extract archives from unknown sources directly into your working directory.

Look especially for references to user home directories, build workspaces, and local package manager prefixes. These absolute paths often do not exist on another machine. System library paths are not necessarily errors. Likewise, @rpath and @loader_path do not automatically mean the configuration is correct: you still need to check which libraries are actually bundled and how their load paths are configured.

After making changes, rebuild and repeat validation. Do not patch files only in the extracted directory and then ship the unchanged original wheel. Delete the temporary directory when the inspection is complete.

4. Perform a Real Installation Outside the Source Tree

First, collect the wheel and all runtime dependencies in a separate directory. This step may access the network. Dependency versions should be governed by the project’s release constraints, and you should save the final list of downloaded packages.

mkdir -p wheelhouse
.wheel-build/bin/python -m pip download \
  --only-binary=:all: --dest wheelhouse dist/*.whl

If a dependency has no matching binary distribution, this step should fail. Do not silently fall back to building from source, as that changes what you are validating.

The following commands create an environment outside the source tree. When prompted, enter the project’s actual import name, which may differ from its distribution name:

read -r -p "Import module: " module
wheelhouse="$(pwd)/wheelhouse"
wheel="$(find "$(pwd)/dist" -maxdepth 1 -name '*.whl' -print)"
sandbox="$(mktemp -d)"
python3 -m venv "$sandbox/venv"
(
  cd "$sandbox"
  ./venv/bin/python -m pip install \
    --no-index --find-links "$wheelhouse" "$wheel"
  ./venv/bin/python -m pip check
  ./venv/bin/python -I - "$module" <<'PY'
import importlib
import sys

module = importlib.import_module(sys.argv[1])
print(getattr(module, "__file__", None))
print(list(getattr(module, "__path__", [])))
PY
)

Verify that the import location is inside the new environment, not the source tree. pip check only checks declared dependency relationships; it does not verify native library loading or invoke lazily loaded functionality. You must also run an application-level operation that actually exercises the extension module—for example, process a small, fixed sample and assert the result.

5. Record the Acceptance Criteria with the Release

For each run, retain at least the commit ID, interpreter details, wheel filename, checksum, dependency list, and application smoke-test results. Record the checksum with shasum -a 256 dist/*.whl to ensure that the file you deliver is the same one you just tested.

Address failures at the appropriate layer: if the tags do not match, revisit the build target; if dynamic libraries are missing, revisit dependency collection; if imports work only inside the source tree, check package discovery rules and resource declarations. Do not hide missing files by broadening the search path.

Finally, repeat installation and execution on the minimum operating system version you claim to support and with the other target interpreters. A successful run on a newer system proves only that the current combination passed. Documenting the scope of validation is more reliable than giving the package a broader compatibility tag.

Frequently asked questions