ModuleNotFoundError: No module named — как исправить

ModuleNotFoundError: No module named '…' означает, что Python не нашёл модуль, который вы импортируете, ни в одной папке из своего пути поиска. Чаще всего причина одна из двух: пакет не установлен или установлен в другой интерпретатор — не тот, которым запускается скрипт.

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

Быстрое решение — установить пакет тем же Python, которым вы запускаете код:

python -m pip install requests     # Windows: можно py -m pip install requests
python3 -m pip install requests    # macOS и Linux

Если ошибка осталась, пройдите по причинам ниже — они расположены от самой частой к редкой.

Пакет не установлен

Сторонние библиотеки (requests, pandas, django, numpy) не входят в Python — их ставят через pip. Посмотрите имя в кавычках в конце ошибки и установите пакет:

python -m pip install requests

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

Пакет установлен в другой интерпретатор или venv

Самая коварная ситуация: вы выполнили pip install, увидели Successfully installed, а импорт всё равно не работает. Значит, pip и python относятся к разным установкам. Так бывает, когда:

• на компьютере несколько версий Python (например, 3.11 и 3.12), а pip в PATH относится к одной из них;
• пакет поставлен в системный Python, а скрипт запускается из venv — или наоборот;
• терминал и IDE используют разные интерпретаторы;
• окружение не активировано в новом окне терминала.

Как проверить

Выведите путь к интерпретатору, который реально запускает ваш код, — добавьте в начало скрипта:

import sys

print(sys.executable)

Затем в терминале посмотрите, куда ставит пакеты ваш pip:

python -m pip --version

pip 25.0.1 from C:\projects\shop\.venv\Lib\site-packages\pip (python 3.12)

Пути должны указывать на одну установку: если скрипт запускается C:\projects\shop\.venv\Scripts\python.exe, pip тоже должен быть из C:\projects\shop\.venv. Проверить конкретный пакет можно командой python -m pip show requests — строка Location покажет, куда он установлен.

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

Установите пакет именно тем интерпретатором, который запускает код. Надёжнее всего — по полному пути из sys.executable:

C:\projects\shop\.venv\Scripts\python.exe -m pip install requests   # Windows
/home/user/shop/.venv/bin/python -m pip install requests              # Linux

Или выберите в IDE тот интерпретатор, куда пакет уже установлен:

• VS Code — Ctrl+Shift+P → Python: Select Interpreter → интерпретатор из .venv;
• PyCharm — Settings → Project → Python Interpreter.

Форма python -m pip вместо голого pip защищает от этой ошибки в будущем — почему, объясняется в статье pip в Python.

Имя пакета не совпадает с именем модуля

Имя для pip install (название дистрибутива на PyPI) и имя для import (название модуля) часто различаются. Если установить «как импортируется», pip либо не найдёт пакет, либо поставит что-то другое.

Ошибка	Что установить
No module named 'cv2'	python -m pip install opencv-python
No module named 'PIL'	python -m pip install Pillow
No module named 'pptx'	python -m pip install python-pptx
No module named 'docx'	python -m pip install python-docx
No module named 'sklearn'	python -m pip install scikit-learn
No module named 'bs4'	python -m pip install beautifulsoup4
No module named 'yaml'	python -m pip install PyYAML
No module named 'dotenv'	python -m pip install python-dotenv

Например, команда pip install cv2 завершится ошибкой, потому что пакета с таким именем на PyPI нет:

ERROR: Could not find a version that satisfies the requirement cv2 (from versions: none)
ERROR: No matching distribution found for cv2

Правильное имя ищите в документации библиотеки или на pypi.org. Подробнее про OpenCV — в статье OpenCV в Python.

Опечатка или неверный регистр

Имена модулей чувствительны к регистру даже в Windows:

>>> import Requests
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'Requests'

Пишите имя так, как указано в документации: requests, django, numpy — строчными; PIL — заглавными.

Модуль убран из стандартной библиотеки

Некоторые модули удаляют из новых версий Python. В Python 3.12 удалены distutils и imp, поэтому старый код или устаревшая библиотека падают с ошибкой:

ModuleNotFoundError: No module named 'distutils'

Что делать: обновить библиотеку, которая импортирует удалённый модуль (python -m pip install --upgrade имя). Для distutils временно помогает установка setuptools — он содержит совместимую реализацию. Если ни то ни другое не подходит, используйте версию Python, которую поддерживает ваша библиотека. Какая версия у вас сейчас — см. как узнать версию Python.

Свой модуль не находится: sys.path и запуск через python -m

Ошибка возникает и для ваших собственных файлов. Python ищет модули в папках из списка sys.path:

import sys

print(sys.path)

Первым элементом в нём стоит папка запускаемого скрипта. При запуске через python -m на этом месте текущий каталог терминала, а в интерактивном режиме — пустая строка, которая тоже означает текущий каталог. Дальше идут стандартная библиотека и site-packages. Рабочий каталог терминала, вопреки ожиданиям, при запуске python путь/к/скрипту.py в поиск не попадает.

Возьмём проект:

shop/
└── app/
    ├── __init__.py
    ├── main.py          # from app.utils.text import slugify
    └── utils/
        ├── __init__.py
        └── text.py

Запуск файла напрямую ломает импорт, потому что в sys.path попадает папка shop/app, а не shop:

C:\projects\shop> python app\main.py
Traceback (most recent call last):
  File "C:\projects\shop\app\main.py", line 1, in <module>
    from app.utils.text import slugify
ModuleNotFoundError: No module named 'app'

Правильно — запустить код как модуль из корня проекта. Путь пишется через точки и без .py:

C:\projects\shop> python -m app.main
hello-world

Так Python добавит в sys.path текущий каталог (shop), и пакет app найдётся. Тот же приём лечит ошибку относительного импорта ImportError: attempted relative import with no known parent package, которая появляется при запуске python app\rel.py для файла с from .utils.text import slugify.

Другие варианты, если python -m не подходит:

• задать переменную окружения PYTHONPATH с путём к корню проекта;
• установить свой проект в окружение в режиме разработки: python -m pip install -e . (нужен pyproject.toml или setup.py);
• в крайнем случае добавить путь в коде через sys.path.append(...) — это работает, но делает проект хрупким.

Подробнее о способах запуска — в статье как запустить Python-скрипт.

Важно: не называйте свои файлы так же, как библиотеки (requests.py, pandas.py, django.py). Python найдёт ваш файл раньше установленного пакета, и вместо ModuleNotFoundError появится AttributeError: partially initialized module 'requests' has no attribute 'get' (most likely due to a circular import). С Python 3.13 сообщение подсказывает причину прямо: (consider renaming '…requests.py' if it has the same name as a library you intended to import).

Jupyter Notebook использует другое ядро

Jupyter запускает код в ядре (kernel), а у ядра может быть свой интерпретатор — не тот, в который вы ставили пакет из терминала. Проверьте в ячейке:

import sys

sys.executable

И устанавливайте пакеты магической командой %pip — она ставит их в окружение текущего ядра:

%pip install pandas

Вариант !pip install запускает первый pip из PATH и может снова промахнуться. После установки перезапустите ядро, если импорт не заработал сразу.

Чек-лист: No module named

1. Скопируйте имя модуля из ошибки и проверьте опечатки и регистр.
2. Узнайте, какой пакет нужно ставить для этого модуля (cv2 → opencv-python).
3. Выведите sys.executable в скрипте и сравните с python -m pip --version.
4. Установите пакет через путь_к_python -m pip install имя.
5. Проверьте интерпретатор в IDE или ядро в Jupyter.
6. Для своих модулей — запускайте из корня проекта через python -m пакет.модуль.

Частые вопросы

Чем ModuleNotFoundError отличается от ImportError?

ModuleNotFoundError — подкласс ImportError, появился в Python 3.6. Он означает, что не найден сам модуль. Обычный ImportError возникает, когда модуль найден, но импортировать из него конкретное имя не удалось: cannot import name 'pathx' from 'os'.

Ошибка No module named ‘django’ при запуске manage.py

Django установлен не в то окружение или окружение проекта не активировано. Активируйте .venv и проверьте python -m pip show django. Установка с нуля описана в статье как установить Django.

Почему в PyCharm работает, а в терминале нет (или наоборот)?

У PyCharm и терминала разные интерпретаторы. Сравните путь в Settings → Project → Python Interpreter с выводом python -c "import sys; print(sys.executable)" в терминале.

No module named pip — как вернуть pip?

pip не установлен в этот интерпретатор. В Windows и macOS его восстанавливает встроенный модуль ensurepip:

python -m ensurepip --upgrade    # Windows: py -m ensurepip --upgrade

В Debian и Ubuntu системный Python поставляется без pip и ensurepip, там выполните sudo apt install python3-pip, а для проектов создайте виртуальное окружение (понадобится пакет python3-venv) — pip в нём есть сразу.

No module named tkinter в Linux

Tkinter входит в стандартную библиотеку, но в Debian и Ubuntu вынесен в отдельный системный пакет. Через pip его не поставить, нужен менеджер пакетов ОС: sudo apt install python3-tk. Подробнее — в статье о Tkinter.

Итог

ModuleNotFoundError: No module named почти всегда решается установкой пакета в правильный интерпретатор: сверьте sys.executable с python -m pip --version и ставьте пакеты через python -m pip. Для своих модулей запускайте код из корня проекта через python -m. Как читать любые сообщения об ошибках, рассказано в руководстве «Ошибки в Python: как читать traceback», а обработку исключений — в статье try/except в Python.