deepinsight/insightface · critical · ImportError

Unable to import dependency onnxruntime.

Error message

Unable to import dependency onnxruntime. 

What it means

insightface's package __init__ does 'import onnxruntime' at import time inside a try/except that converts ImportError into this message. onnxruntime is a hard dependency because all insightface models execute as ONNX graphs, so 'import insightface' aborts entirely when it's missing or unloadable.

Source

Thrown at python-package/insightface/__init__.py:10

# coding: utf-8
# pylint: disable=wrong-import-position
"""InsightFace: A Face Analysis Toolkit."""
from __future__ import absolute_import

try:
    #import mxnet as mx
    import onnxruntime
except ImportError:
    raise ImportError(
        "Unable to import dependency onnxruntime. "
    )

__version__ = '1.0.1'

from . import model_zoo
from . import utils
from . import app
from . import data
from . import thirdparty

View on GitHub (pinned to 7fadd420c2)

Solutions

1. pip install onnxruntime (CPU) or an onnxruntime-gpu version matching your CUDA, into the same interpreter/venv.
2. Verify with 'python -c "import onnxruntime"' in the exact interpreter used for insightface.
3. If onnxruntime-gpu fails to load, fix CUDA/cuDNN versions or fall back to plain onnxruntime.
4. Reinstall a corrupted wheel: pip install --force-reinstall onnxruntime.

Example fix

# before
import insightface  # ImportError: Unable to import dependency onnxruntime.

# after (shell)
# pip install onnxruntime
import insightface  # ok

import importlib.util
if importlib.util.find_spec('onnxruntime') is None:
    raise SystemExit('onnxruntime missing — run: pip install onnxruntime')
import insightface

def has_onnxruntime() -> bool:
    import importlib.util
    return importlib.util.find_spec('onnxruntime') is not None

try:
    import insightface
except ImportError as e:
    if 'onnxruntime' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'onnxruntime'])
        import insightface
    else:
        raise

When it happens

Trigger: import insightface (or any module importing it) in an environment where 'import onnxruntime' raises ImportError: not installed, installed into another interpreter, or the binary wheel fails to load (incompatible CUDA onnxruntime-gpu, old glibc).

Common situations: Fresh venv without requirements; source install that skipped runtime deps; onnxruntime-gpu/CUDA version mismatch failing to import; pip resolving into a different python than the one running the code.

Related errors

• Library not found at {lib_path}. System: {system}, Architect
• ModelScope is not available. You have two options: 1. Instal
• ModelScope is not available. Please install it with: pip ins
• The rec.addmaskparam command requires mxnet. Please install
• The rec.addmaskparam command requires optional mask renderin

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