No module named 'insightface' in ComfyUI: Windows Fix

ComfyUI shows ModuleNotFoundError: No module named 'insightface' (or Cannot import ... module for custom nodes: No module named 'insightface') when a face node cannot import InsightFace. Fix the Python environment ComfyUI actually uses, not a random system Python.

InsightFace is a face detection and recognition library used by ReActor (face swap), IPAdapter FaceID, InstantID, and PuLID. When it is missing, those nodes fail to load but the rest of ComfyUI usually keeps working. On PyPI it ships as a source distribution, so on Windows a plain pip install insightface often fails while trying to build native code:

error: Microsoft Visual C++ 14.0 or greater is required.
ERROR: Failed building wheel for insightface
fatal error C1083: Cannot open include file: 'Python.h': No such file or directory

Severity: medium — install it only if your workflow needs face-swap, FaceID, InstantID, PuLID, or another InsightFace-based feature.

Step 1: Use the correct Python

Install into the Python that starts ComfyUI:

Check the Python version first (python --version, or .\python_embeded\python.exe -s --version for portable). The wheel must match it.

Step 2: Install a matching community wheel only if you trust its source

On Windows, the community commonly uses pre-built wheels from the ReActor ecosystem. Choose the wheel that matches your Python version:

For the official Windows portable package, replace python -m pip with .\python_embeded\python.exe -s -m pip.

Step 3: Install ONNX Runtime only if the workflow needs it

InsightFace uses ONNX Runtime as its inference backend. CPU ONNX Runtime is often enough:

python -m pip install onnxruntime

For NVIDIA GPU acceleration:

python -m pip install onnxruntime-gpu

GPU ONNX Runtime must match the CUDA/cuDNN family of your PyTorch runtime. If it fails with onnxruntime_providers_cuda.dll, use the ONNX / ONNXRuntime guide before changing more packages.

Step 4: Treat NumPy downgrades as a last resort

Do not downgrade NumPy just because InsightFace is mentioned — current ComfyUI environments can legitimately use NumPy 2.x. Only consider it if you see a real NumPy compatibility error from the face plugin you need, and back up first:

python -m pip install "numpy<2"

Then restart ComfyUI and test only the face workflow that needed the change.

Step 5: Restart and verify

Restart ComfyUI (a plugin that already failed to import will not register its nodes until the next startup), then verify in the same environment:

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

Expected output is usually 0.7.3 for the community wheel path.

Still not working?

Collect the full IMPORT FAILED traceback, python --version, python -c "import torch; print(torch.__version__, torch.version.cuda)", and whether you installed CPU or GPU ONNX Runtime before choosing a support path.

Source References

• ComfyUI troubleshooting overview
• ComfyUI custom node troubleshooting guide
• ComfyUI model troubleshooting guide
• InsightFace GitHub repository