InsightFace Missing in ComfyUI

Symptoms

When ComfyUI starts, you see one of these errors in the terminal log:

ModuleNotFoundError: No module named 'insightface'

or:

Cannot import ... module for custom nodes: No module named 'insightface'

Cause

InsightFace is an open-source face detection and recognition library developed by the deepinsight team. The following ComfyUI plugins depend on it:

• ReActor (ComfyUI-ReActor) — face swapping
• IPAdapter FaceID (ComfyUI_IPAdapter_plus) — facial feature transfer
• InstantID (ComfyUI-InstantID) — identity-preserving generation
• PuLID — face-identity-driven generation

When InsightFace is missing, all face-related nodes in these plugins will fail to load, but the rest of ComfyUI continues to work normally.

Why it is especially hard to install on Windows

The insightface Python package contains Cython extension code that must be compiled from C++ source during installation. PyPI does not provide a pre-built wheel for Windows, so pip install insightface will almost certainly fail unless your system already has a full C++ build toolchain installed.

Severity

Medium — must be installed if you need face-swap or other face-related workflows.

Common error messages when installation fails

Running pip install insightface directly may produce one of these errors:

error: Microsoft Visual C++ 14.0 or greater is required.
Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/

Building wheel for insightface (pyproject.toml) ... error
error: subprocess-exited-with-error

fatal error C1083: Cannot open include file: 'Python.h': No such file or directory

ERROR: Failed building wheel for insightface
ERROR: Could not build wheels for insightface, which is required to install pyproject.toml-based projects

All of these point to the same root cause: a missing C++ build environment. The solutions below bypass the compilation step entirely.

Solutions

Option 1: Install a pre-built wheel (recommended)

This is the simplest and most reliable approach — install a pre-compiled .whl file with no build tools required.

Step 1: Check your Python version

Open a terminal in the Wonderful Launcher Environments page and run:

python --version

Note the version number (e.g. 3.10.x, 3.11.x, 3.12.x, or 3.13.x).

Step 2: Install the matching pre-built wheel

Run the command that corresponds to your Python version:

Python 3.10:

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp310-cp310-win_amd64.whl

Python 3.11:

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp311-cp311-win_amd64.whl

Python 3.12:

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp312-cp312-win_amd64.whl

Python 3.13:

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp313-cp313-win_amd64.whl

These wheel files are provided by Gourieff, the author of the ReActor plugin, and are widely used in the community.

Step 3: Install onnxruntime

InsightFace requires onnxruntime as its inference backend. If you have not installed it yet:

For NVIDIA GPUs (recommended):

pip install onnxruntime-gpu

For systems without a dedicated GPU, or with an AMD GPU:

pip install onnxruntime

Step 4: Handle potential NumPy version conflicts

InsightFace 0.7.3 is not compatible with NumPy 2.x. If you see a NumPy-related error after installation (e.g. AttributeError: module 'numpy' has no attribute 'int'), downgrade NumPy:

pip install "numpy<2"

Step 5: Restart ComfyUI

Restart ComfyUI for the changes to take effect.

Option 2: Install Visual C++ Build Tools and compile from source

If no pre-built wheel matches your environment (for example, your Python version does not have a corresponding wheel), you can install the build tools and compile from source.

1. Download and install Microsoft C++ Build Tools
2. In the installer, select the Desktop development with C++ workload
3. Restart your computer after installation
4. In the Wonderful Launcher terminal, run:

   pip install cython
   pip install insightface
   

Note: The full Build Tools installation requires roughly 6-8 GB of disk space. If you only need it for insightface, Option 1 is recommended instead.

Verify the installation

Run the following command in the terminal. If it prints a version number without errors, the installation was successful:

python -c "import insightface; print(insightface.__version__)"

Expected output: 0.7.3

Still not working?

If none of the above solutions resolve the issue, contact support through the Contact Us button in the app and include the full error output from the terminal.