deepinsight/insightface · critical · RuntimeError

Library not found at {lib_path}. System: {system}, Architect

Error message

Library not found at {lib_path}. System: {system}, Architecture: {arch}

What it means

get_lib_path() computed the expected install location for the InspireFace native shared library (package_dir/libs/<platform>/<arch>/<lib_name>) and verified it exists, but the file is missing. The directory is even created with makedirs, so the error specifically means the binary payload was never shipped/downloaded into the Python package.

Source

Thrown at cpp-package/inspireface/python/inspireface/modules/core/native.py:85

            except:
                # If detection fails, assume native x64
                arch = 'x64'
        elif machine == 'arm64':
            arch = 'arm64'
            
    # Validate that all necessary parameters were set
    if not all([platform_dir, lib_name, arch]):
        raise RuntimeError(
            f"Unsupported platform: system={system}, machine={machine}")
    
    # Construct the full library path
    dir_path = package_dir / 'libs' / platform_dir / arch
    os.makedirs(dir_path, exist_ok=True)
    lib_path = dir_path / lib_name
    
    # Verify that the library file exists
    if not lib_path.exists():
        raise RuntimeError(
            f"Library not found at {lib_path}. "
            f"System: {system}, Architecture: {arch}")
    
    return str(lib_path)

try:    
    _LIBRARY_FILENAME = get_lib_path()
except Exception as e:
    print(e)

_int_types = (ctypes.c_int16, ctypes.c_int32)
if hasattr(ctypes, "c_int64"):
    # Some builds of ctypes apparently do not have ctypes.c_int64
    # defined; it's a pretty good bet that these builds do not
    # have 64-bit pointers.
    _int_types += (ctypes.c_int64,)
for t in _int_types:
    if ctypes.sizeof(t) == ctypes.sizeof(ctypes.c_size_t):

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Reinstall cleanly: pip uninstall inspireface && pip install inspireface --force-reinstall
2. Verify the file: ls <site-packages>/inspireface/libs/<platform>/<arch>/ and confirm the expected library name exists
3. If installing from source, build the C++ package first so the libs are copied into python/inspireface/libs
4. On Windows, check antivirus/quarantine and restore or whitelist the DLL

Example fix

# before: RuntimeError: Library not found at .../libs/linux/x64/libinspireface.so
pip uninstall -y inspireface
# after
pip install --force-reinstall --no-cache-dir inspireface
python -c "import inspireface; print('ok')"

import inspireface, pathlib
p = pathlib.Path(inspireface.__file__).parent / 'libs'
assert any(p.rglob('libinspireface*')) or any(p.rglob('InspireFace*')), 'native libs missing — reinstall'

When it happens

Trigger: First use of InspireFace after a pip install from source (no bundled libs), a partially corrupted wheel install, manually deleting the libs directory, or a packaging bug where the .so/.dll/.dylib was excluded (e.g. slim docker image, .gitignore applied during packaging).

Common situations: pip install from a git clone instead of the release wheel; docker multi-stage builds that strip binaries; antivirus quarantining the DLL on Windows; upgrading the package with --no-cache-dir leaving stale files; CI caching a broken site-packages.

Related errors

• Unsupported platform: system={system}, machine={machine}
• Unknown calling convention '{}' for function '{}'
• Could not load %s.
• HERR_INVALID_PARAM
• HERR_INVALID_FACE_FEATURE

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/05256edd4eb7d3b3. Report an issue: GitHub.