Ошибка No module named: почему Python не видит библиотеку

ModuleNotFoundError означает, что текущий Python не нашёл модуль с именем из последней строки traceback. Сначала выведите sys.executable, затем проверьте пакет командой этого же интерпретатора через python -m pip show ИМЯ. Ниже разберём четыре главные причины: библиотека не установлена, пакет попал в другой Python, неверно написан импорт или собственный файл лежит вне пути поиска.

Ошибка выглядит одинаково, но исправляется по-разному. Для No module named 'requests' обычно нужна установка пакета. Для No module named 'app.utils' важнее структура проекта и способ запуска. А если импорт падает только в IDE, почти наверняка терминал и редактор выбрали разные интерпретаторы.

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

Во время import Python ищет уже загруженный модуль, встроенные модули и доступные каталоги. Список каталогов хранится в sys.path: туда входят папка запускаемого скрипта, стандартная библиотека, site-packages текущего окружения и некоторые настройки среды. Если подходящего модуля нет, возникает ModuleNotFoundError.

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

Библиотека не установлена в текущий Python

Пакеты из PyPI устанавливаются в site-packages конкретного интерпретатора. Поэтому команда pip install requests может сработать, а import requests продолжит падать, если pip относится к другому Python. Надёжная форма связывает установщик и интерпретатор через -m.

python -c "import sys; print(sys.executable)"
python -m pip show requests
python -m pip install requests
python -c "import requests; print(requests.__file__)"
python main.py

Если pip на Windows не запускается отдельной командой, используйте py -m pip. Эта форма запускает установщик как модуль выбранного Python и не зависит от отдельного ярлыка pip.exe в PATH.

Терминал и IDE используют разные окружения

VS Code, PyCharm, Jupyter и обычный терминал могут запускать разные Python. У каждого собственный site-packages. Установка пакета в глобальный Python не делает его доступным в .venv, а пакет внутри .venv не появляется в остальных окружениях.

import sys

print("Python:", sys.executable)
print("Version:", sys.version)
print("Search path:")
for folder in sys.path:
    print(" -", folder)

Запустите этот файл из IDE и из обычного терминала. Если первая строка различается, выберите правильный interpreter в настройках проекта. Для виртуального окружения путь обычно заканчивается на .venv\Scripts\python.exe в Windows или .venv/bin/python в macOS и Linux.

Библиотека установлена, но не для того интерпретатора: это самая частая причина ошибки только в IDE.

Для каждого проекта полезно создавать отдельную .venv. Подробная схема есть в статье зачем нужны виртуальные окружения Python.

Python не видит ваш собственный модуль

Если импортируется ваш файл, устанавливать пакет из PyPI не нужно. Проверьте структуру проекта, рабочую папку и полное имя. При запуске скрипта Python добавляет его каталог в начало пути поиска. Родитель соседней папки может туда не попасть, если команда запущена из неожиданного места.

my-project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   └── utils.py
└── tests/
    └── test_utils.py

# app/main.py
from app.utils import format_name

print(format_name("Кодик"))

Для такой структуры перейдите в my-project и запускайте модуль командой python -m app.main. Тогда корень проекта попадает в путь поиска, а полный импорт app.utils читается одинаково. Запуск python app/main.py меняет стартовый контекст и часто маскирует ошибку структуры.

Алгоритм исправления по последней строке traceback

Читайте traceback снизу вверх. Последняя строка сообщает тип ошибки и первое имя, которое Python не смог найти. Затем определите, относится оно к сторонней библиотеке, вашему пакету или вложенному модулю. После каждой правки запускайте одну короткую команду импорта, а не всё приложение.

Правильная ветка зависит не от текста import, а от того, где должен находиться отсутствующий модуль.