Если что-то не работает
ModuleNotFoundError на сервере: почему локально работает, а там нет
Коротко
ModuleNotFoundError на сервере почти всегда значит, что библиотека стоит у вас на компьютере, но не указана в requirements.txt, поэтому сервер её не установил. Второе по частоте — имя для установки отличается от имени в import: import PIL ставится как Pillow, import cv2 как opencv-python-headless, import telegram как python-telegram-bot. Если же не находится ваш собственный модуль, проверьте, что файл попал в загрузку и что регистр букв в имени совпадает: сервер на Linux отличает utils.py от Utils.py. Строка с ошибкой в логах сборки или запуска прямо называет модуль, которого не хватает.
- ModuleNotFoundError: No module named X означает, что Python не нашёл модуль X ни среди установленных библиотек, ни среди файлов проекта.
- Сервер ставит только те библиотеки, которые перечислены в requirements.txt или в разделе dependencies файла pyproject.toml.
- Имя в import и имя пакета для установки часто не совпадают: PIL — это Pillow, cv2 — opencv-python, sklearn — scikit-learn, bs4 — beautifulsoup4.
- Linux различает регистр букв в именах файлов, поэтому import Utils находит utils.py на Windows и macOS, но не на сервере.
- Проверить список зависимостей заранее можно в чистом виртуальном окружении: если проект запускается там, он запустится и на сервере.
На компьютере всё работает, а после публикации в логах одна строка: ModuleNotFoundError: No module named и имя модуля. Это одна из самых частых ошибок при переносе проекта на Python куда угодно — на хостинг, на VPS, на компьютер друга. Код при этом обычно в порядке: дело в том, что у вас на машине за месяцы работы скопились библиотеки, о которых проект ничего не говорит, а сервер начинает с чистого листа и ставит только то, что перечислено явно.
Хорошая новость: ошибка всегда называет, чего именно не хватает. Остаётся понять, к какому из пяти случаев она относится — библиотеки нет в списке, она названа иначе, нужна другая версия Python, ваш собственный файл не нашёлся или его перекрыл файл с тем же именем. Ниже разбор по порядку, от самой частой причины к редким.
| В коде | В requirements.txt | Комментарий |
|---|---|---|
| import PIL | Pillow | Старый пакет PIL давно не поддерживается, его заменил Pillow |
| import cv2 | opencv-python-headless | На сервере нет экрана, поэтому нужна версия без окон и графического интерфейса |
| import telegram | python-telegram-bot | Пакет с коротким именем telegram — посторонний и к этой библиотеке отношения не имеет |
| import dotenv | python-dotenv | Пакет с именем dotenv — другая библиотека |
| import sklearn | scikit-learn | Пакет sklearn для установки устарел и не работает |
| import bs4 | beautifulsoup4 | Цифра 4 в имени пакета обязательна |
| import yaml | PyYAML | Имени yaml для установки нет |
| import jwt | PyJWT | Пакет jwt — другая библиотека с похожим именем и другими функциями |
Найдите в логах имя модуля, которого не хватает#
Откройте логи сборки или запуска и найдите последнюю строку перед остановкой: ModuleNotFoundError: No module named и имя в кавычках. Выше обычно указаны файл и номер строки, где стоит этот import. Сразу решите, чей это модуль: если имя похоже на библиотеку, вроде requests, aiogram или PIL, дело в зависимостях, а если на файл из вашей папки, вроде config, handlers или utils, дело в структуре проекта. От этого зависит, какой из следующих шагов ваш.
Добавьте библиотеку в requirements.txt#
Сервер ставит только то, что перечислено в requirements.txt в корне проекта или в разделе dependencies файла pyproject.toml. Если библиотеку вы когда-то поставили командой pip install у себя, а в файл не записали, локально она есть, а на сервере её нет. Откройте requirements.txt, добавьте недостающую строку с именем пакета и загрузите проект заново. Если файла нет вовсе, создайте его: одна библиотека на строку, только то, что реально импортирует код.
Сверьте имя для установки с именем в import#
У многих библиотек имя в коде и имя пакета для установки разные: import PIL ставится как Pillow, import cv2 как opencv-python-headless, import telegram как python-telegram-bot, import dotenv как python-dotenv, import sklearn как scikit-learn, import bs4 как beautifulsoup4, import yaml как PyYAML. Если в requirements.txt записано имя из import, установится либо ничего, либо посторонний пакет с похожим именем, и ошибка останется. Если не уверены, найдите библиотеку на сайте PyPI: там прямо написана команда установки.
Проверьте версию Python#
Некоторые модули есть только в определённых версиях Python: что-то убрали из стандартной библиотеки, что-то появилось недавно, а часть пакетов не выпускает сборки под самые новые версии. Если ошибка касается модуля, который вы точно не ставили сами, вроде distutils или imp, скорее всего, версия Python на сервере новее вашей. Узнайте свою версию командой python --version и, если нужна именно она, укажите её файлом .python-version в корне проекта — Netrun соберёт проект на этой версии. Ещё лучше обновить код или библиотеку под актуальный Python.
Проверьте, что ваш собственный файл доехал и назван правильно#
Если не находится ваш модуль, например config или handlers, сначала убедитесь, что файл вообще попал в загрузку: его могли исключить правила .gitignore или он остался в другой папке. Затем сверьте регистр букв: Windows и macOS считают utils.py и Utils.py одним файлом, а сервер на Linux — разными, поэтому import Utils там не сработает. Наконец, проверьте путь: импорт вида from app.utils import ... работает, только если запуск идёт из папки, где лежит app. Перенесите точку запуска в корень проекта или поправьте путь в import.
Убедитесь, что ваш файл не перекрывает библиотеку#
Если назвать свой файл так же, как библиотеку, например telegram.py, requests.py или openai.py, Python найдёт сначала его и не доберётся до настоящей библиотеки. Тогда ошибка выглядит странно: модуль вроде бы есть, но внутри него не находится нужное имя, или Python жалуется на частично загруженный модуль. Переименуйте свой файл во что-то своё, вроде my_bot.py, и удалите рядом папку __pycache__, если она попала в архив.
Проверьте проект в чистом окружении перед публикацией#
Самый надёжный способ поймать все недостающие зависимости разом — повторить то, что делает сервер. Создайте пустое виртуальное окружение командой python -m venv, активируйте его, поставьте зависимости командой pip install -r requirements.txt и запустите проект. Всё, чего не хватает, всплывёт сразу на вашем компьютере, и не придётся публиковать проект по кругу. Саму папку venv в архив класть не нужно: библиотеки ставятся при сборке.
ModuleNotFoundError на сервере — это почти всегда расхождение между вашим компьютером и списком зависимостей, а не поломка кода. Запишите в requirements.txt всё, что импортирует проект, сверьте имена пакетов и проверьте свои файлы на регистр букв — этого хватает в подавляющем большинстве случаев. В Netrun логи сборки и запуска видны в кабинете в реальном времени, поэтому имя недостающего модуля вы увидите сразу, а исправленную версию загрузите поверх старой. Попробовать Netrun.
Частые вопросы
Почему у меня на компьютере всё работает, а на сервере нет?
Потому что на вашем компьютере библиотека уже стоит — вы ставили её когда-то для этого или другого проекта. Сервер начинает с пустого окружения и ставит только то, что перечислено в requirements.txt. Всё, что вы ставили вручную и не записали в файл, на сервере просто отсутствует.
Я добавил пакет в requirements.txt, а ошибка осталась — что не так?
Скорее всего, вы записали имя из import, а пакет для установки называется иначе: например, нужно Pillow вместо PIL или python-telegram-bot вместо telegram. Проверьте точное имя на сайте PyPI. Ещё одна причина — файл requirements.txt лежит не в корне проекта, а во вложенной папке, и его не нашли.
Можно ли просто сделать pip freeze и положить результат в requirements.txt?
Можно, но так в файл попадает всё окружение целиком, включая лишние пакеты, пакеты только для Windows и строки с путями к папкам вашего компьютера. Из-за этого сборка часто падает уже на установке. Надёжнее перечислить руками только то, что импортирует код, или прогнать freeze в чистом виртуальном окружении проекта.
Что делать, если не находится мой собственный модуль, а не библиотека?
Проверьте три вещи: файл попал в загрузку, регистр букв в имени файла совпадает с тем, что написано в import, и путь импорта начинается от папки, из которой запускается проект. Сервер на Linux строже к регистру, чем Windows и macOS, поэтому Config.py и config.py для него разные файлы.
Чем ModuleNotFoundError отличается от ImportError?
ModuleNotFoundError — частный случай ImportError: модуль не найден вообще. Просто ImportError с текстом cannot import name значит, что модуль найден, но внутри нет нужного имени — обычно из-за другой версии библиотеки или из-за вашего файла, который назван так же, как библиотека.
Можно ли запустить проект на Python — Django, Flask или FastAPI?
Да. Положите зависимости в requirements.txt — Netrun определит Python и соберёт проект сам. Django, Flask и FastAPI поддерживаются; приложение должно слушать порт из переменной окружения, а ключи и доступ к базе задаются как секреты, а не в коде.
Где посмотреть логи и статус проекта?
На странице проекта есть статус, логи и история событий — по ним видно, что происходит с проектом прямо сейчас. Лента логов показывает и более ранние строки: пролистайте её вверх, и они подгрузятся сами.