Python package and native libraries

The Python API uses ctypes to call the native SDK. To switch from CPU to TensorRT or Rockchip NPU, download the matching 1.2.4 shared SDK from SDK downloads, or build it for your target. CoreML requires a source build. Select the library from Python or include it in a wheel, keeping the wrapper and native SDK matched.

For CPU use, install the published 1.2.4.post3 package with python -m pip install inspireface opencv-python. It includes the 1.2.4 native library. This chapter covers replacing that library and building your own wheel; available packages are listed in the SDK overview.

Prepare the native SDK and wrapper

Python needs a shared library: libInspireFace.dll on Windows, libInspireFace.so on Linux or libInspireFace.dylib on macOS. With the current PyPI wrapper and a matching 1.2.4 release library, continue to select a shared library.

To build your own library or edit the wrapper, complete source preparation, then follow Windows, Linux, macOS, NVIDIA or Rockchip. Enable ISF_BUILD_SHARED_LIBS=ON and prepare the source wrapper as described below.

On Apple platforms, the new Objective-C / Swift frameworks are an additional integration route for native apps. Python still loads the raw macOS dylib, not InspireFace.xcframework, InspireFaceSwift.framework or an iOS static archive. build_macos_arm64.sh and build_macos_x86.sh produce that dylib. The arm64 CoreML script produces a raw .a; use the custom shared build for Python instead.

The CMake configuration generates python/version.txt. If you built the SDK in this checkout, it is already in place. When reusing a matching 1.2.4 SDK built elsewhere, the Python version file must contain only 1.2.4:

python -c "from pathlib import Path; Path('python/version.txt').write_text('1.2.4\n')"

The SDK root’s version.txt contains a label such as InspireFace Version: 1.2.4; do not copy that label into the Python version file. Keep the Python source revision matched to the library. The Windows wheel script below prepares this file automatically.

From the InspireFace repository root, create a Python environment and install the wrapper:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ./python

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ./python

An editable installation reads the wrapper from your checkout. It does not compile the native SDK. Choose the native library before the first import.

Select or replace a shared library

For Linux, point to the complete .so file path:

export INSPIREFACE_LIBRARY_PATH=/absolute/path/to/libInspireFace.so
python -c 'import inspireface as isf; print(isf.version())'

On macOS, use the .dylib path:

export INSPIREFACE_LIBRARY_PATH=/absolute/path/to/libInspireFace.dylib
python -c 'import inspireface as isf; print(isf.version())'

On Windows, use the .dll path in PowerShell:

$env:INSPIREFACE_LIBRARY_PATH = 'C:\sdk\InspireFace\lib\libInspireFace.dll'
python -c "import inspireface as isf; print(isf.version())"

INSPIREFACE_LIBRARY_PATH accepts a file, not a directory. A missing file raises RuntimeError; a library that cannot be loaded raises ImportError with the loader error. When an override is set, loading fails directly instead of falling back to the bundled library. Clear it with unset INSPIREFACE_LIBRARY_PATH on Linux/macOS or Remove-Item Env:INSPIREFACE_LIBRARY_PATH -ErrorAction SilentlyContinue in PowerShell to use the package's library again.

The Python process and the native library must have the same architecture. For example, x86_64 Python under Rosetta needs an x86_64 library even on an Apple Silicon Mac.

Check native dependencies

Check the library on the target system. On Linux:

file /absolute/path/to/libInspireFace.so
ldd /absolute/path/to/libInspireFace.so

On macOS:

file /absolute/path/to/libInspireFace.dylib
otool -L /absolute/path/to/libInspireFace.dylib

On Windows, run this in a Visual Studio Developer PowerShell:

dumpbin /DEPENDENTS C:\sdk\InspireFace\lib\libInspireFace.dll

The published CPU DLL needs the Microsoft Visual C++ v14 x64 runtime. It includes its CPU inference dependency, so no additional inference DLL is needed.

Resolve any missing runtime libraries before importing Python. TensorRT/CUDA and Rockchip builds also need the backend runtime installed on the target; copying libInspireFace.so alone does not install those dependencies. See the corresponding platform chapter for runtime setup.

Put the library into a wheel

The bundled library lives under python/inspireface/modules/core/libs/. The directory names use x64 and arm64, while wheel tags use x86_64 and aarch64 on Linux.

These package paths cover 64-bit Python processes. For Rockchip packaging on this page, use the Linux aarch64 SDK, such as the RK356x/RK3588 build.

The following commands package a Linux x86_64 library. Run them from the repository root in the activated environment. A fresh staging directory keeps files from an earlier wheel build out of the result.

if ! test -f python/version.txt; then
  echo "Missing python/version.txt: build the SDK or prepare its matching version number first." >&2
  exit 1
fi
python -m pip install build

export INSPIRE_FACE_TARGET_PLATFORM=linux
export INSPIRE_FACE_TARGET_ARCH=x64
export INSPIRE_FACE_TARGET_AARCH_MAPPING=linux_x86_64
ISF_NATIVE=/absolute/path/to/libInspireFace.so

ISF_WHEEL_STAGE="$(mktemp -d)"
cp -R python/inspireface "$ISF_WHEEL_STAGE/"
cp python/{setup.py,pyproject.toml,README.md,version.txt,post} "$ISF_WHEEL_STAGE/"
ISF_BUNDLE_DIR="$ISF_WHEEL_STAGE/inspireface/modules/core/libs/$INSPIRE_FACE_TARGET_PLATFORM/$INSPIRE_FACE_TARGET_ARCH"
mkdir -p "$ISF_BUNDLE_DIR"
cp "$ISF_NATIVE" "$ISF_BUNDLE_DIR/libInspireFace.so"

python -m build --wheel --outdir "$PWD/python/dist" "$ISF_WHEEL_STAGE"

For Windows, use the dedicated packaging script below. For Linux aarch64, use arm64 and linux_aarch64. For macOS, follow the complete packaging example below, including its explicit deployment tag.

The wheel version comes from python/version.txt plus the suffix in python/post. The current source uses 1.2.4 and .post3, producing inspireface-1.2.4.post3-py3-none-linux_x86_64.whl. The native SDK version remains 1.2.4.

Choose the directory and wheel tag

These three packaging variables have different jobs:

If unset, setup.py chooses directories and tags from the build host. Its Linux default is manylinux2014; for a local build with no manylinux compatibility check, the linux_x86_64 or linux_aarch64 tag above is more appropriate. A portable manylinux wheel requires building against the intended compatibility baseline and checking its external dependencies.

The 1.2.4 wrapper produces a py3-none-<platform> wheel: ctypes has no CPython extension ABI dependency, but the wheel contains a native library and is platform-specific. The package declares Python 3.7 or newer. Changing a tag or renaming a library does not change its CPU architecture, libc requirements or backend dependencies.

Cross-packaging can run on a different host after you have built the target library. Set all three variables explicitly, then test the resulting wheel on the actual target. INSPIREFACE_LIBRARY_PATH only controls runtime loading; it does not select the library bundled by setup.py.

Build a Windows x64 wheel

For a normal CPU installation, use PyPI. To package a modified SDK, prepare the Windows build environment, then run this from the repository root with x64 Python:

.\command\build_wheel_windows.ps1 -PythonExecutable python

With CMake 4, first build the SDK with the policy compatibility option, then use -SdkDirectory below. The wheel script does not pass that option through to CMake.

The script builds a Release CPU DLL and packages it as py3-none-win_amd64. Native tests are skipped by default; add -TestNative to run them during the build. If the SDK is already built, reuse its install directory instead:

.\command\build_wheel_windows.ps1 -PythonExecutable python `
  -SdkDirectory 'C:\sdk\inspireface-windows-x64-1.2.4'

-SdkDirectory points to the root containing version.txt and InspireFace/lib/libInspireFace.dll. This route needs Python but does not invoke the C++ compiler. Do not combine it with -TestNative, -BuildDirectory or -InspireCVSource.

The script checks the SDK version, x64 PE format, release runtime dependencies and wheel contents. It rejects Debug DLLs and builds that need extra backend DLLs. Packaging uses a temporary directory and leaves the checkout's bundled libraries unchanged.

The current output is python/dist/inspireface-1.2.4.post3-py3-none-win_amd64.whl, with a .manifest.json recording the DLL imports and SHA-256 hashes. Set -OutputDirectory to choose another output folder. An existing wheel is retained unless -Force is supplied.

Install the result in a fresh environment:

python -m venv .venv-wheel-check
.\.venv-wheel-check\Scripts\python.exe -m pip install python/dist/inspireface-1.2.4.post3-py3-none-win_amd64.whl
Remove-Item Env:INSPIREFACE_LIBRARY_PATH -ErrorAction SilentlyContinue
Remove-Item Env:PYTHONPATH -ErrorAction SilentlyContinue
.\.venv-wheel-check\Scripts\python.exe -I -c "import inspireface as isf; print(isf.__version__); print(isf.version()); print(isf.diagnostic_info())"

Run the complete detection example with this environment's Python and a local model to check inference. The wheel contains the CPU DLL; the model pack remains a separate file. The target machine needs the x64 Visual C++ runtime.

Package the current macOS SDK

Start with the Develop source. For Apple Silicon, this complete example builds the CPU library with a macOS 14.0 deployment target and packages it with the corresponding wheel tag. Run it in the activated Python environment from the repository root. Inspect the printed architecture, minimum OS and dependencies before distributing the wheel.

MACOSX_DEPLOYMENT_TARGET=14.0 VERSION=1.2.4 \
  bash command/build_macos_arm64.sh --jobs 4

ISF_APPLE_SDK="$PWD/build/inspireface-macos-apple-silicon-arm64-1.2.4"
ISF_NATIVE="$ISF_APPLE_SDK/InspireFace/lib/libInspireFace.dylib"
xcrun lipo -info "$ISF_NATIVE"
xcrun vtool -show-build "$ISF_NATIVE"
otool -L "$ISF_NATIVE"
python -c "from pathlib import Path; Path('python/version.txt').write_text('1.2.4\n')"

python -m pip install build
export INSPIRE_FACE_TARGET_PLATFORM=darwin
export INSPIRE_FACE_TARGET_ARCH=arm64
export INSPIRE_FACE_TARGET_AARCH_MAPPING=macosx_14_0_arm64

ISF_WHEEL_STAGE="$(mktemp -d)"
cp -R python/inspireface "$ISF_WHEEL_STAGE/"
cp python/{setup.py,pyproject.toml,README.md,version.txt,post} "$ISF_WHEEL_STAGE/"
ISF_BUNDLE_DIR="$ISF_WHEEL_STAGE/inspireface/modules/core/libs/darwin/arm64"
mkdir -p "$ISF_BUNDLE_DIR"
cp "$ISF_NATIVE" "$ISF_BUNDLE_DIR/libInspireFace.dylib"
python -m build --wheel --outdir "$PWD/python/dist" "$ISF_WHEEL_STAGE"

With the current .post3 suffix, the result is inspireface-1.2.4.post3-py3-none-macosx_14_0_arm64.whl. For Intel, use build_macos_x86.sh, its inspireface-macos-intel-x86-64-1.2.4 output directory, x64 for the package directory / target architecture variable, and a matching macosx_<major>_<minor>_x86_64 tag. Set the deployment target for that build explicitly too.

When packaging an existing Apple XCFramework bundle, take the raw dylib from SDKs/macosx-arm64/InspireFace/lib/ or SDKs/macosx-x86_64/InspireFace/lib/, with the version number from the same slice. Package each architecture separately; including an XCFramework does not make a Python wheel universal.

To package CoreML on arm64, first use the CoreML shared CMake build. Its install/InspireFace/lib/libInspireFace.dylib can replace ISF_NATIVE above. Keep the matching minimum OS, architecture and version file, and deploy an Apple model pack for CoreML inference.

Inspect the wheel

Replace the filename below with the wheel you just built. Check that it contains the expected native library and platform tag:

python -m zipfile -l python/dist/inspireface-1.2.4.post3-py3-none-linux_x86_64.whl

Find the entry ending in inspireface/modules/core/libs/linux/x64/libInspireFace.so; the archive may place it under a .data/purelib/ prefix. Model packs are separate from the wheel; deploy the matching pack alongside your application.

Install and verify the packaged library

For Windows, use the verification commands in Windows wheel packaging. The following shell commands are for Linux/macOS. Test in a new environment so the editable wrapper does not mask the installed package. Clear the local-library override and any source PYTHONPATH before importing:

python3 -m venv .venv-wheel-check
source .venv-wheel-check/bin/activate
python -m pip install python/dist/inspireface-1.2.4.post3-py3-none-linux_x86_64.whl
unset INSPIREFACE_LIBRARY_PATH
unset PYTHONPATH

Run this from the repository root or another directory outside python/:

import platform
import sys
import inspireface as isf
from inspireface.modules.core import native

print("Python:", sys.executable)
print("Architecture:", platform.machine())
print("Wrapper:", isf.__version__)
print("Native:", isf.version())
print("Package:", isf.__file__)
print("Loaded library:", native._LIBRARY_FILENAME)

native._LIBRARY_FILENAME is an internal diagnostic value in the 1.2.4 wrapper. Use it here to confirm which file was loaded; application code should use the public API. The printed package and library paths should both point inside .venv-wheel-check when testing a bundled wheel.

Finally, run the Python detection example with a local model pack. A successful import checks library loading; a detection run also checks the backend, model and image-processing path.

Existing packaging scripts

The repository also has scripts that compile the SDK and copy its library into the Python package:

Run Linux packaging in the provided Docker environment; the aarch64 container needs an ARM64 host or configured emulation. These scripts rebuild the native library and write wheels into python/dist/. For an already compiled TensorRT, CoreML or Rockchip library, use the explicit packaging steps above.

For macOS, use the Apple SDK packaging steps on this page. The existing build_wheel_macos_arm64.sh and build_wheel_macos_x86.sh still invoke a separate direct CMake build: they do not use the new Apple driver, do not explicitly select the target architecture or deployment version, and inherit setup.py's default wheel tag. Their filenames alone do not establish the resulting library's compatibility.

The directory selection, tags and runtime override are implemented in python/setup.py, _library_path.py and _native_loader.py.