Ошибка ModuleNotFoundError в Python: что означает No module named и как исправить

Вы скачали Python-скрипт, запустили его и получили ошибку ModuleNotFoundError: No module named. Обычно это означает, что программа не может найти нужную библиотеку. Разберём, как установить её, почему ошибка иногда остаётся после pip install и что проверить в VS Code, PyCharm и Jupyter Notebook.

Как быстро исправить ModuleNotFoundError

Представим, что вы скачали Python-скрипт для обработки Excel-таблицы с рекламной статистикой. В нём используется библиотека Pandas, которая помогает загружать данные, рассчитывать показатели и формировать отчёты.

При запуске появляется сообщение:

Traceback (most recent call last):

  File "report.py", line 1, in <module>

    import pandas

ModuleNotFoundError: No module named 'pandas'

Python не смог найти Pandas. Для начала попробуем установить библиотеку и запустить программу ещё раз.

Откройте терминал

Терминал — это окно, в котором можно вводить команды для компьютера. Не нужно вставлять команду установки в Python-файл рядом с import pandas.

Если вы работаете в VS Code, выберите Terminal → New Terminal. Внизу редактора откроется панель, куда можно вводить команды.

В Windows также можно открыть PowerShell через меню «Пуск». На macOS используйте приложение «Терминал», а в Linux — терминал вашей системы.

Если вы видите строку >>>, значит, находитесь внутри интерактивного Python. Выйдите из него командой exit(), чтобы вернуться в обычный терминал.

Установите библиотеку

Введите в терминале:

python -m pip install pandas

Нажмите Enter и дождитесь завершения установки. Команда состоит из трёх частей: python запускает Python, pip отвечает за установку библиотек, а pandas — название нужного пакета.

На macOS и Linux вместо python иногда используется python3:

python3 -m pip install pandas

Если в Windows команда python не распознаётся, а команда py доступна, можно попробовать:

py -m pip install pandas

При успешной установке терминал обычно показывает сообщение вроде Successfully installed. Если появляется Requirement already satisfied, пакет уже есть в той версии Python, через которую вы запустили установку.

Запустите скрипт ещё раз

Вернитесь к файлу report.py и снова запустите программу. Если ошибка исчезла, проблема решена.

Для отдельной проверки можно выполнить в терминале:

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

Если Pandas доступен, Python выведет номер его версии. Например, вместо ошибки вы увидите число вида 2.x.x или 3.x.x — в зависимости от установленной версии.

Если сообщение No module named ‘pandas’ осталось, не устанавливайте библиотеку бесконечно. Скорее всего, скрипт запускается через другую версию Python. Дальше разберём, как это выяснить.

Что означает ошибка ModuleNotFoundError

ModuleNotFoundError — это ошибка, которая возникает, когда Python не может найти модуль при выполнении команды import.

Модуль — это часть программы с готовым кодом. Например, requests используют для отправки запросов к сайтам и API, pandas — для работы с таблицами, а matplotlib — для построения графиков.

Чтобы использовать библиотеку, её сначала устанавливают, а затем подключают в Python-коде:

import requests

Если программа не может найти requests, вы увидите:

ModuleNotFoundError: No module named 'requests'

Название после No module named — первая подсказка. Именно его нужно проверить.

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

Иногда ошибка возникает и внутри сторонней библиотеки. Например, вы подключаете один пакет, а тот пытается загрузить другой. Поэтому полезно смотреть не только последнюю строку сообщения, но и весь текст ошибки: там указано, какие файлы выполнялись перед сбоем.

Почему pip install не помогает, хотя библиотека установлена

Одна из самых частых причин — на компьютере есть несколько версий Python.

Допустим, вы установили библиотеку в обычном терминале Windows. Затем открыли проект в VS Code и запустили скрипт. Но редактор использует другую версию Python, в которой этой библиотеки нет.

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

Как проверить, какой Python запускает программу

Откройте файл, в котором возникает ошибка, и временно добавьте перед проблемным импортом:

import sys

print(sys.executable)

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

Например, в Windows:

C:\Projects\reports\.venv\Scripts\python.exe

Это означает, что проект работает через Python внутри папки .venv.

Теперь откройте терминал и выполните:

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

Сравните оба пути. Если они отличаются, терминал и скрипт используют разные версии Python.

Как установить пакет именно в нужный Python

Используйте полный путь, который показала команда sys.executable.

Например, в PowerShell:

& "C:\Projects\reports\.venv\Scripts\python.exe" -m pip install pandas

Здесь & помогает PowerShell правильно запустить программу по указанному пути, даже если в названии папки есть пробелы.

На macOS и Linux путь к Python внутри проекта обычно выглядит так:

./.venv/bin/python -m pip install pandas

Пути в этих примерах условные. Не нужно копировать их без изменений: используйте расположение Python на своём компьютере.

После установки повторите запуск скрипта. Если причина была в разных окружениях, ошибка должна исчезнуть.

Как создать виртуальное окружение Python

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

Представим, что вы создаёте три программы: одна анализирует Excel-отчёты, вторая работает с API рекламной платформы, а третья запускает ИИ-помощника. Им могут требоваться разные библиотеки и даже разные версии одних и тех же пакетов.

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

Для нового проекта откройте терминал в его папке и выполните:

python -m venv .venv

Появится папка .venv, в которой будет находиться отдельное окружение Python. На macOS и Linux для создания окружения может понадобиться python3.

Теперь установим Pandas именно в него.

Для Windows:

.\.venv\Scripts\python.exe -m pip install pandas

Для macOS и Linux:

./.venv/bin/python -m pip install pandas

Активировать окружение отдельной командой необязательно: мы уже указали полный путь к нужному Python.

Если вы открыли чужой проект, сначала посмотрите, как он устроен. Возможно, виртуальное окружение там уже настроено, а зависимости перечислены в requirements.txt или pyproject.toml. В таком случае лучше использовать предусмотренный проектом способ установки, а не создавать ещё одну папку .venv.

Как исправить ModuleNotFoundError в VS Code

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

Например, в терминале Pandas работает, а при нажатии кнопки запуска появляется No module named ‘pandas’. Первым делом проверьте выбранный интерпретатор.

Интерпретатор — это программа, которая выполняет Python-код. Чтобы выбрать правильный, выполните следующие действия:

1. Откройте проект в VS Code.
2. Нажмите Ctrl + Shift + P в Windows или Linux либо Cmd + Shift + P на macOS.
3. Введите Python: Select Interpreter.
4. Выберите Python, который относится к вашему проекту. Если используется .venv, ищите путь внутри этой папки.
5. Откройте новый терминал и запустите программу повторно.

Выбранный Python также можно увидеть в строке состояния VS Code. Если в списке нет нужного окружения, проверьте панель Environment Managers. В ней отображаются найденные версии Python и виртуальные окружения.

Иногда VS Code ещё не обнаружил новое окружение. В таком случае можно запустить команду Python Environments: Refresh All Environment Managers, которая обновляет список.

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

Как исправить ModuleNotFoundError в PyCharm

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

Откройте настройки PyCharm и перейдите в Python → Interpreter. Здесь отображается Python, который использует проект, и его расположение.

Если выбран не тот интерпретатор, переключитесь на нужный. Например, на Python внутри .venv, если именно там установлена библиотека.

PyCharm позволяет устанавливать пакеты без терминала. Для этого откройте View → Tool Windows → Python Packages, найдите нужную библиотеку и нажмите Install.

Допустим, программа выдаёт No module named ‘matplotlib’. Проверьте, какой Python выбран для проекта, затем найдите matplotlib в Python Packages и установите пакет в это окружение.

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

Что делать с ошибкой в Jupyter Notebook

В Jupyter Notebook код выполняется в отдельном процессе Python, который называется ядром (kernel). Поэтому библиотека может быть установлена в системе, но отсутствовать в ядре, выбранном для ноутбука.

Например, вы открыли ноутбук для анализа CSV-файла и получили No module named ‘numpy’. Сначала проверьте, какой Python использует Jupyter:

import sys

print(sys.executable)

Для установки пакета непосредственно в окружение текущего IPython-ядра можно выполнить в ячейке:

%pip install numpy

После установки некоторых библиотек ядро нужно перезапустить. Если ошибка не исчезла, проверьте, какое ядро выбрано в интерфейсе ноутбука.

No module named pandas, cv2, PIL, sklearn: что устанавливать

Иногда проблема заключается в названии пакета. Например, в коде вы пишете import cv2, но устанавливать нужно не cv2, а opencv-python.

Похожая ситуация с обработкой изображений: библиотека называется Pillow, а подключается через PIL.

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

Например, для ошибки No module named ‘cv2’ используйте:

python -m pip install opencv-python

А если Python не находит PIL:

python -m pip install Pillow

Для некоторых названий нет одного универсального пакета. Например, модуль telegram часто используется библиотекой python-telegram-bot, а Crypto — библиотекой pycryptodome. Но существуют и другие пакеты с похожими названиями. Поэтому в таких случаях лучше сначала посмотреть документацию проекта.

Это не просто формальность. На PyPI могут существовать разные пакеты с похожими названиями, поэтому устанавливать случайную библиотеку только по тексту ошибки небезопасно.

Если вы работаете с рекламными таблицами, отдельно пригодится наш материал «NumPy или Pandas: что выбрать для работы с данными». В нём объясняем, какие задачи удобнее решать каждой библиотекой и как использовать их для обработки статистики.

Что делать, если Python не находит ваш собственный файл

ModuleNotFoundError может появиться даже без сторонних библиотек. Например, вы написали несколько Python-файлов и пытаетесь подключить функцию из одного в другой.

Допустим, проект выглядит так:

project/

└── app/

    ├── __init__.py

    ├── main.py

    └── utils.py

Файл __init__.py оставьте пустым. В utils.py добавьте:

def helper():

    return "Модуль найден"

А в main.py напишите:

from app.utils import helper

print(helper())

Теперь перейдите в терминале в папку project.

Если запустить программу командой:

python app/main.py

Python может выдать:

ModuleNotFoundError: No module named 'app'

Это происходит из-за того, как Python ищет файлы при запуске программы. В данном случае ему нужно явно указать, что main.py является частью пакета app.

Попробуйте запустить программу из папки project так:

python -m app.main

Результат:

Модуль найден

Таким способом Python запускает файл как модуль проекта и правильно находит app.utils.

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

Редкие ошибки: No module named pip, tkinter, distutils и pkg_resources

Некоторые сообщения No module named связаны не с обычными библиотеками, а с особенностями установки Python или устаревшим кодом. В таких случаях команда pip install с названием из ошибки не всегда подходит.

No module named pip

pip — инструмент, который устанавливает библиотеки Python. Если программа не находит сам pip, сначала проверьте его наличие:

python -m pip --version

В некоторых установках Python восстановить pip можно командой:

python -m ensurepip --upgrade

Но она работает не во всех сборках Python. Например, в Linux pip иногда устанавливается отдельным системным пакетом.

Если появляется сообщение externally-managed-environment, не пытайтесь обходить ограничение случайными командами из интернета. Обычно оно означает, что системным Python управляет операционная система. Для собственных проектов лучше создать виртуальное окружение.

No module named tkinter

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

Проверить наличие можно так:

python -m tkinter

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

В Debian и Ubuntu для системного Python модуль можно установить через:

sudo apt install python3-tk

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

No module named distutils

distutils использовали старые инструменты сборки Python-пакетов. Начиная с Python 3.12 этот модуль удалён из стандартной библиотеки.

Если ошибка появилась после обновления Python, скорее всего, какая-то часть проекта использует устаревший код. Проверьте совместимость библиотеки с вашей версией Python и попробуйте найти её обновлённую версию. В отдельных проектах совместимость обеспечивает setuptools, но это зависит от конкретной зависимости.

No module named pkg_resources

pkg_resources раньше входил в setuptools, но давно считался устаревшим. Начиная с setuptools 82.0.0 его удалили из пакета.

Поэтому обычное обновление setuptools теперь не гарантирует исправление ошибки. Если pkg_resources используется в вашем коде, стоит перейти на современные возможности importlib.metadata или importlib.resources. Если ошибка внутри сторонней библиотеки, ищите её совместимую версию.

No module named exceptions

Такая ошибка может возникать в старом коде для Python 2. Там существовал отдельный модуль exceptions, но в Python 3 стандартные исключения доступны без него.

Например, не нужно подключать Exception через:

from exceptions import Exception

Для обычной обработки ошибок достаточно встроенных классов:

try:

    number = int("abc")

except ValueError:

    print("Не удалось преобразовать строку в число")

Если проблема находится внутри сторонней библиотеки, проверьте, поддерживает ли она Python 3.

Что проверить, если ModuleNotFoundError не исчезает

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

Для начала проверьте следующее:

1. Название модуля. Посмотрите последнюю строку ошибки и выясните, какой пакет нужно установить. Его название может отличаться от имени в import.
2. Путь к Python. Выведите sys.executable в программе, которая выдаёт ошибку.
3. Установленные библиотеки. Проверьте пакет через python -m pip show название_пакета, используя тот же интерпретатор.
4. Способ запуска. Если модуль находится внутри вашего проекта, проверьте папки, названия файлов и возможность запуска через python -m.
5. Версии зависимостей. Если ошибка появилась после обновления Python или библиотеки, проверьте совместимость.

При работе с более сложными проектами подобные ошибки могут возникать сразу в нескольких зависимостях. Например, для создания ИИ-агентов часто используют фреймворки и отдельные пакеты для подключения моделей и инструментов. В нашем разборе LangChain есть практический пример подготовки такого проекта на Python.

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

FAQ