Ошибка ModuleNotFoundError: No module named 'insightface' возникает в тот момент, когда интерпретатор Python доходит до строки import insightface, но не находит установленный пакет в текущем окружении. Это типичная ситуация при запуске проектов распознавания лиц — например, при работе с Stable Diffusion (расширения вроде ReActor или Roop), а также при запуске собственных скриптов анализа изображений.
Причина почти всегда одна из трёх: пакет не установлен, установлен в другое виртуальное окружение или установка завершилась с ошибкой, которую пропустили. Ниже разберём диагностику и все способы исправления — от простой установки до решения проблем со сборкой зависимостей на Windows.
Что означает ошибка и когда она появляется
Сообщение No module named 'insightface' — это стандартный ответ Python на попытку импорта отсутствующего модуля. Интерпретатор ищет пакет в путях sys.path, не находит его и останавливает выполнение скрипта с трассировкой стека.
Пакет insightface — это библиотека для анализа лиц: детекция, распознавание, выравнивание и извлечение эмбеддингов. Она активно используется в проектах замены лиц и верификации. Библиотека зависит от onnxruntime, numpy, opencv-python и ряда других пакетов, поэтому её установка сложнее, чем у обычного чисто-питоновского модуля.
- 🔍 Пакет вообще не устанавливался в текущее окружение — самая частая причина.
- 🐍 Установка выполнена в системный Python, а скрипт запускается из виртуального окружения (или наоборот).
- 💥 Установка прервалась с ошибкой компиляции, но пользователь не заметил сообщения в консоли.
- 📁 Локальный файл проекта назван
insightface.pyи конфликтует с реальным пакетом.
Шаг 1. Проверьте, какой Python и окружение используются
Прежде чем что-то устанавливать, убедитесь, что вы работаете с тем же интерпретатором, под которым запускается скрипт. Выполните в терминале:
python -c "import sys; print(sys.executable)"Команда покажет полный путь к интерпретатору. Если путь ведёт в папку venv проекта, а вы устанавливали пакеты глобально — вот и причина ошибки. Дополнительно проверьте, видит ли pip нужный пакет:
python -m pip show insightfaceЕсли вывод пустой — пакет не установлен именно в это окружение. Обратите внимание: вызов pip через python -m pip гарантирует, что установка пойдёт в тот же интерпретатор, а не в какой-то другой, найденный в PATH.
Шаг 2. Установите insightface правильно
Стандартная установка выполняется одной командой. Активируйте нужное виртуальное окружение и выполните:
python -m pip install insightfaceНа Linux и macOS установка обычно проходит без проблем, так как для части зависимостей доступны готовые сборки. На Windows процесс может завершиться ошибкой компиляции — об этом отдельный раздел ниже.
После установки проверьте импорт напрямую:
python -c "import insightface; print(insightface.__version__)"Если версия вывелась без ошибок — проблема решена. Если появилась новая ошибка про другой модуль (например, onnxruntime), установите недостающую зависимость аналогичной командой.
☑️ Проверка после установки
Шаг 3. Решение проблем сборки на Windows
На Windows установка insightface нередко падает с ошибкой вроде error: Microsoft Visual C++ 14.0 or greater is required. Это значит, что pip попытался собрать часть кода из исходников, а компилятора в системе нет.
Решение — установить Build Tools для Visual Studio с компонентом «Разработка классических приложений на C++». После установки инструментов сборки перезапустите терминал и повторите команду установки. Альтернативный путь — поискать готовый wheel-файл под вашу версию Python, однако источник таких файлов должен быть доверенным.
⚠️ Внимание: не скачивайте wheel-пакеты insightface с неизвестных сайтов. Скомпилированные бинарники из недоверенных источников могут содержать вредоносный код. Безопасные варианты — официальный PyPI или сборка из исходников с установленными Build Tools.
Также проверьте версию Python: для очень новых или очень старых версий готовых сборок зависимостей может не быть. Если установка упорно не проходит, попробуйте версию Python, для которой зависимости точно опубликованы, — список поддерживаемых версий указан на странице пакета в PyPI.
Конфликты окружений: venv, Conda и Jupyter
Если вы работаете в Jupyter Notebook, помните: ядро ноутбука может использовать другой интерпретатор, чем терминал. Устанавливайте пакет прямо из ячейки:
import sys
!{sys.executable} -m pip install insightface
При использовании Conda сначала активируйте нужное окружение командой conda activate имя_окружения и только потом ставьте пакет через pip. Смешивание conda- и pip-пакетов допустимо, но pip-пакеты лучше ставить после всех conda-установок, чтобы избежать конфликтов зависимостей.
Для пользователей Stable Diffusion WebUI ситуация особая: расширения вроде ReActor ставят зависимости в собственное окружение venv внутри папки WebUI. Если расширение сообщает об ошибке insightface, установку нужно выполнять именно в этот venv, а не в системный Python. Путь к интерпретатору обычно выглядит как venv\Scripts\python.exe внутри каталога WebUI.
Типичные ошибки и их признаки
| Симптом | Вероятная причина | Решение |
|---|---|---|
| ModuleNotFoundError при запуске | Пакет не установлен в текущее окружение | python -m pip install insightface |
| Ошибка «Microsoft Visual C++ 14.0 required» | Нет компилятора для сборки на Windows | Установить Build Tools для Visual Studio |
| Import работает в терминале, но не в скрипте | Разные интерпретаторы / окружения | Сверить sys.executable в обоих случаях |
| Ошибка про onnxruntime после установки | Не доустановилась зависимость | python -m pip install onnxruntime |
| ImportError с другим текстом | Локальный файл insightface.py затеняет пакет | Переименовать файл проекта |
⚠️ Внимание: не создавайте в проекте файлы с именамиinsightface.pyили папкиinsightface— Python найдёт их раньше настоящего пакета, и вы получите запутанные ошибки импорта, даже если библиотека установлена корректно.
Если ничего не помогло
Иногда проще пересоздать окружение, чем искать источник конфликта. Удалите папку venv, создайте окружение заново и установите зависимости из requirements.txt проекта, добавив туда insightface, если его там нет.
Проверьте также, не ограничивает ли установку антивирус или корпоративная политика: сборка C++-расширений создаёт временные файлы, которые иногда блокируются. При подозрении временно добавьте папку проекта в исключения и повторите установку.
Как полностью пересоздать окружение
1) Удалите папку venv. 2) Выполните python -m venv venv. 3) Активируйте: venv\Scripts\activate (Windows) или source venv/bin/activate (Linux/macOS). 4) Выполните python -m pip install -r requirements.txt и python -m pip install insightface. 5) Проверьте импорт командой python -c "import insightface".
В крайнем случае изучите полный лог установки: pip выводит детальный текст ошибки сборки, где указано, какой именно компонент не собрался. Поиск по этому фрагменту лога обычно приводит к конкретному решению для вашей версии Python и ОС.
Частые вопросы
Почему pip пишет, что пакет установлен, но ошибка остаётся?
Скорее всего, pip и ваш скрипт используют разные интерпретаторы. Сравните вывод python -m pip show insightface и путь из sys.executable внутри скрипта. Устанавливайте пакет через python -m pip тем же интерпретатором, которым запускаете проект.
Нужна ли отдельная установка onnxruntime для insightface?
Обычно onnxruntime подтягивается автоматически как зависимость. Если после установки insightface появляется ошибка про onnxruntime, установите его отдельно: python -m pip install onnxruntime. Для работы на GPU существует вариант onnxruntime-gpu.
Как исправить ошибку в Stable Diffusion WebUI с расширением ReActor?
Установите пакет в окружение самого WebUI: запустите venv\Scripts\python.exe -m pip install insightface из папки WebUI. Если установка падает с ошибкой компиляции, сначала установите Build Tools для Visual Studio. Точные требования расширения смотрите в его документации — они могут меняться между версиями.
Можно ли установить insightface без компилятора на Windows?
Если на PyPI есть готовый wheel под вашу версию Python — да, pip скачает его автоматически, и компилятор не понадобится. Если готовой сборки нет, pip попытается собрать пакет из исходников, и тогда Build Tools обязательны. Проверить доступные файлы можно на странице пакета в PyPI в разделе «Download files».
Что делать, если в проекте есть файл insightface.py?
Переименуйте его — например, в face_analysis.py — и удалите рядом папку __pycache__, чтобы Python не подхватил закэшированную версию. После этого импорт будет обращаться к настоящему установленному пакету.