{"record":{"id":"e109a48700ec77af","repo":"deepinsight/insightface","slug":"unable-to-import-dependency-onnxruntime","errorCode":null,"errorMessage":"Unable to import dependency onnxruntime. ","messagePattern":"Unable to import dependency onnxruntime\\. ","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"python-package/insightface/__init__.py","lineNumber":10,"sourceCode":"# coding: utf-8\n# pylint: disable=wrong-import-position\n\"\"\"InsightFace: A Face Analysis Toolkit.\"\"\"\nfrom __future__ import absolute_import\n\ntry:\n    #import mxnet as mx\n    import onnxruntime\nexcept ImportError:\n    raise ImportError(\n        \"Unable to import dependency onnxruntime. \"\n    )\n\n__version__ = '1.0.1'\n\nfrom . import model_zoo\nfrom . import utils\nfrom . import app\nfrom . import data\nfrom . import thirdparty\n","sourceCodeStart":1,"sourceCodeEnd":21,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/__init__.py#L1-L21","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["pip install onnxruntime (CPU) or an onnxruntime-gpu version matching your CUDA, into the same interpreter/venv.","Verify with 'python -c \"import onnxruntime\"' in the exact interpreter used for insightface.","If onnxruntime-gpu fails to load, fix CUDA/cuDNN versions or fall back to plain onnxruntime.","Reinstall a corrupted wheel: pip install --force-reinstall onnxruntime."],"exampleFix":"# before\nimport insightface  # ImportError: Unable to import dependency onnxruntime.\n\n# after (shell)\n# pip install onnxruntime\nimport insightface  # ok","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec('onnxruntime') is None:\n    raise SystemExit('onnxruntime missing — run: pip install onnxruntime')\nimport insightface","typeGuard":"def has_onnxruntime() -> bool:\n    import importlib.util\n    return importlib.util.find_spec('onnxruntime') is not None","tryCatchPattern":"try:\n    import insightface\nexcept ImportError as e:\n    if 'onnxruntime' in str(e):\n        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'onnxruntime'])\n        import insightface\n    else:\n        raise","preventionTips":["Declare onnxruntime explicitly in your requirements.","Verify 'python -c \"import onnxruntime\"' inside deploy containers before startup."],"tags":["dependency","onnxruntime","import","installation"],"backgroundTag":"missing-required-dependency","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}