ModuleNotFoundError: No module named — почему pip install не помогает и как найти нужный Python

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import pandas
ModuleNotFoundError: No module named 'pandas'

Первая реакция — pip install pandas. Пакет ставится, пишет Successfully installed, а ошибка остаётся. Так почти всегда потому, что pip поставил пакет в один Python, а скрипт запускается другим. На Windows их бывает три-четыре одновременно: с python.org, из Microsoft Store, внутри Anaconda, в виртуальном окружении проекта.

Проверка за одну команду

Выясни, какой Python на самом деле запускает твой код. Добавь в начало скрипта две строки:

import sys
print(sys.executable)

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

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

pip --version в конце строки показывает, к какому Python он привязан. Если пути разные, причина найдена. Надёжное правило на будущее — ставить пакеты тем же интерпретатором, которым запускаешь код:

python -m pip install pandas

Если скрипт запускается через лаунчер py, то и пакет ставь им: py -m pip install pandas. Можно и полным путём, который напечатал sys.executable: C:\путь\к\python.exe -m pip install pandas.

Пять частых причин

Где запускаешь	Что обычно не так	Что сделать
Терминал, проект с venv	Окружение не активировано, и pip поставил пакет в системный Python	.\venv\Scripts\activate, потом снова pip install. Если активация падает с «выполнение сценариев отключено», читай отдельную статью
VS Code	Внизу справа выбран не тот интерпретатор	Ctrl+Shift+P → «Python: Select Interpreter» → выбери venv проекта
PyCharm	В настройках проекта свой интерпретатор	Settings → Project → Python Interpreter, ставь пакет прямо оттуда
Jupyter Notebook	Ядро не то, в котором стоит пакет	Прямо в ячейке %pip install pandas, затем перезапусти ядро
Двойной клик по .py	Windows открывает его «Python по умолчанию», не тем, что в терминале	Запускай из терминала или ставь пакет в интерпретатор, который печатает sys.executable

Имя модуля ≠ имя пакета

Вторая по частоте причина: в import одно имя, а в pip install нужно другое. pip install cv2 просто не найдёт пакета, а иногда найдёт чужой.

В коде	Ставить
import cv2	pip install opencv-python
from PIL import Image	pip install Pillow
import sklearn	pip install scikit-learn
import yaml	pip install PyYAML
from bs4 import BeautifulSoup	pip install beautifulsoup4
import docx	pip install python-docx
from dotenv import load_dotenv	pip install python-dotenv
import telegram	pip install python-telegram-bot
import win32api	pip install pywin32
import fitz	pip install PyMuPDF

Если модуля нет в таблице, поищи его на pypi.org или посмотри requirements.txt проекта, откуда взят код.

Когда пакет точно стоит, а ошибка остаётся

Файл назван как модуль. Скрипт pandas.py, telegram.py или random.py перекрывает настоящую библиотеку: Python импортирует твой файл вместо неё. Переименуй его и удали папку __pycache__ рядом.

Нет модуля внутри пакета. No module named 'telegram.ext' при установленном telegram обычно значит, что стоит не тот пакет или старая версия. Удали и поставь заново: python -m pip uninstall telegram python-telegram-bot, потом python -m pip install python-telegram-bot.

Относительные импорты. No module named 'utils' при файле utils.py в соседней папке — это про то, откуда ты запускаешь скрипт. Запускай из корня проекта (python -m app.main) или положи файлы в одну папку.

Версия Python слишком новая. Некоторые пакеты выходят под новый Python с задержкой. pip тогда пытается собрать пакет из исходников и падает с failed building wheel, а в коде остаётся No module named. Смотри вывод pip целиком, а не последнюю строку.

Если pip сам не запускается

"pip" не является внутренней или внешней командой — это уже вопрос PATH, а не модуля. python -m pip ... работает и без PATH к pip. Если не находится и сам python, Windows может перехватывать команду заглушкой Microsoft Store. Отключается в «Параметры → Приложения → Дополнительные параметры приложений → Псевдонимы выполнения приложений»: выключи оба пункта python.exe и python3.exe.

Отдать это агенту

Вся диагностика выше — это пять-шесть команд, которые надо запустить в правильном порядке и прочитать результат. Дока делает это на твоём компьютере: открой папку проекта и напиши «скрипт падает с No module named pandas, почини». Агент проверит sys.executable, найдёт venv, поставит пакет в нужный интерпретатор и запустит скрипт ещё раз. Каждую команду ты видишь до запуска и подтверждаешь сам.

Если пишешь первого бота, пригодится статья про Telegram-бота на aiogram.