Почему Python падает с ModuleNotFoundError и как исправить

Ошибка ModuleNotFoundError в Python означает, что интерпретатор не смог найти модуль во время выполнения импорта. Для исправления нужно определить используемый Python, проверить окружение и убедиться, что зависимость установлена именно там, откуда запускается программа.

Что означает ModuleNotFoundError

Исключение ModuleNotFoundError появляется при попытке загрузить модуль:

import requests

Если модуль недоступен в путях поиска Python, выполнение завершается ошибкой:

ModuleNotFoundError: No module named 'requests'

Частые причины проблемы:

• пакет не установлен в текущем окружении;
• запускается другой интерпретатор Python, чем тот, где установлен пакет;
• виртуальное окружение не активировано или выбрано неверно;
• имя пакета для установки отличается от имени, используемого в import;
• локальный файл или каталог влияет на поиск модуля.

Перед установкой зависимости проверьте, какой именно Python выполняет код. Во многих случаях пакет установлен, но не в том окружении, которое использует приложение или IDE.

Применимые версии Python и ограничения

Методы из статьи подходят для современных версий Python 3, включая окружения с модулем venv и установкой пакетов через pip. Конкретные команды могут отличаться в зависимости от операционной системы, способа установки Python и выбранного менеджера окружений.

Если проект использует conda, Poetry, Pipenv или другой инструмент управления зависимостями, применяйте команды этого инструмента. Примеры с python -m pip относятся к окружениям, где зависимости управляются через pip.

Быстрый сценарий диагностики

Причина ошибки обычно зависит от того, когда она появилась:

• После установки пакета: проверьте, что установка выполнялась для того же интерпретатора, который запускает программу.
• После смены IDE: сравните выбранный интерпретатор в редакторе с результатом sys.executable в терминале.
• После клонирования проекта: создайте или активируйте окружение и установите зависимости из файла проекта.

Проверка используемого Python

Сначала определите интерпретатор, который запускает программу:

python --version
python -c "import sys; print(sys.executable)"

В некоторых системах вместо python используется:

python3 --version
python3 -c "import sys; print(sys.executable)"

Значение sys.executable показывает путь к фактически используемому интерпретатору. Сравните его с настройками проекта и IDE.

Проверка интерпретатора в IDE

Если ошибка возникает только при запуске из редактора кода, проверьте выбранное окружение проекта. IDE может использовать другой Python, чем терминал.

• откройте настройки интерпретатора проекта;
• выберите окружение, соответствующее нужному Python;
• сравните путь с результатом sys.executable;
• повторите запуск после изменения настроек.

Проверка установки пакета

Проверяйте наличие зависимости через тот же Python, который запускает программу:

python -m pip show имя_пакета

Например:

python -m pip show requests

Для просмотра установленных пакетов используется:

python -m pip list

Форма python -m pip связывает вызов pip с конкретным интерпретатором и помогает избежать установки пакета в другое окружение.

Исправление установкой зависимости

Если пакет отсутствует, установите его в выбранное окружение:

python -m pip install имя_пакета

После установки проверьте импорт:

python -c "import имя_модуля; print('ok')"

Имя пакета и имя модуля могут отличаться. Например, название в команде установки не всегда совпадает с названием после import, поэтому проверяйте документацию конкретной библиотеки.

Проверка виртуального окружения

Виртуальные окружения изолируют зависимости проектов. Пакет, установленный глобально, не обязательно доступен внутри окружения приложения.

Создание окружения стандартным модулем Python:

python -m venv .venv

Активация зависит от системы.

Windows:

.venv\Scripts\activate

Linux и macOS:

source .venv/bin/activate

После активации снова проверьте окружение:

python -c "import sys; print(sys.executable)"
python -m pip list

Если используется conda

В проектах conda сначала проверьте активное окружение и используйте менеджер, которым оно управляется:

conda env list
conda list

Если пакет должен устанавливаться через conda, используйте соответствующую команду установки. Если часть зависимостей устанавливается через pip внутри conda-окружения, убедитесь, что pip относится к этому же Python.

python -m pip show имя_пакета

Проверка файла зависимостей

Если проект содержит список зависимостей, устанавливайте его целиком. Это обычно надёжнее, чем исправлять каждую ошибку импорта отдельно.

Для файла requirements.txt используется:

python -m pip install -r requirements.txt

После успешной настройки окружения можно зафиксировать текущие зависимости:

python -m pip freeze > requirements.txt

Для проектов с другими менеджерами используйте принятый в проекте механизм фиксации зависимостей, например файлы конфигурации Poetry или Pipenv.

Поиск конфликтов имён

Иногда проблема связана не с отсутствием пакета, а с тем, какой модуль загружается. Например, в проекте может находиться файл с именем установленной библиотеки:

project/
├── requests.py
└── main.py

Python ищет модули по путям из sys.path. В типичной структуре запуска каталог проекта может присутствовать среди этих путей, поэтому локальный файл способен повлиять на результат импорта раньше установленного пакета. Точный порядок зависит от способа запуска и настроек окружения.

Проверить расположение загруженного модуля можно только после успешного импорта:

python -c "import имя_модуля; print(имя_модуля.__file__)"

Если импорт завершается ошибкой ModuleNotFoundError, сначала проверяйте интерпретатор, окружение и установленные пакеты.

Диагностика через sys.path

Python использует список путей sys.path для поиска модулей. Посмотреть фактическое значение можно так:

python -c "import sys; print('\n'.join(sys.path))"

Состав sys.path зависит от способа запуска, виртуального окружения, типа установки Python и настроек проекта. Отсутствие ожидаемого пути может указывать на неправильное окружение, но ручное изменение sys.path обычно не заменяет корректную установку зависимостей.

Типовые ошибки и решения

Проверка результата

После исправления выполните последовательную проверку:

1. Проверьте путь запускаемого Python через sys.executable.
2. Убедитесь, что пакет установлен именно в этом окружении.
3. Проверьте настройки IDE, если запуск выполняется через редактор.
4. Проверьте расположение модуля через module.__file__ только после успешного импорта.
5. Повторите запуск приложения или тестов.
6. Зафиксируйте рабочие зависимости, например создав актуальный requirements.txt через python -m pip freeze > requirements.txt или используя механизм выбранного менеджера проекта.

Итоговый чек-лист

• Определён интерпретатор Python, который выполняет код.
• Проверено активное окружение проекта.
• Пакет проверен через тот же Python и менеджер зависимостей.
• Настройки IDE совпадают с окружением проекта.
• Исключены конфликты имён файлов и каталогов.
• Зависимости зафиксированы принятым в проекте способом.

Ограничения проверки

Команды и расположение окружений могут отличаться в зависимости от операционной системы, версии Python и выбранного инструмента управления зависимостями. Для conda, Poetry, Pipenv и других менеджеров используйте документацию конкретного инструмента.

Источники

• Python Documentation: Built-in Exceptions
• Python Documentation: venv — Creation of virtual environments
• pip Documentation
• Python Packaging User Guide