2 октября 2026 г.

ModuleNotFoundError: No module named … — как собрать requirements.txt для бота

На своём компьютере бот запускается, а на сервере падает в первую же секунду с ModuleNotFoundError: No module named 'dotenv' (или 'telebot', 'aiogram', 'PIL' — подставьте своё). Код тот же, просто на сервере не установлена библиотека, которую он импортирует.

Что значит эта ошибка

Python дошёл до строки import … и не нашёл такого модуля. Дома он есть, потому что когда-то вы сделали pip install руками и забыли. Сервер про это ничего не знает: он ставит ровно то, что перечислено в requirements.txt, и ничего сверх.

Типичный пример из реального деплоя:

Traceback (most recent call last):
  File "/app/01bot.py", line 8, in <module>
    from dotenv import load_dotenv
ModuleNotFoundError: No module named 'dotenv'

В requirements.txt был aiogram, но не было python-dotenv.

Причины по убыванию вероятности

1. Библиотеки просто нет в requirements.txt: поставили руками, а в файл не дописали.
2. В файл записали имя из import, а пакет называется иначе. Например, dotenv вместо python-dotenv. pip честно ставит что-то другое или вообще падает на сборке.
3. Файла requirements.txt нет в корне репозитория: лежит во вложенной папке или не закоммичен.
4. Не та мажорная версия библиотеки: модуль есть, но нужного подмодуля в нём нет (классика — aiogram 2 против 3, ниже).

Имя импорта ≠ имя пакета

На этом спотыкаются чаще всего. Самые частые пары для ботов:

import в коде          →  строка в requirements.txt
dotenv                 →  python-dotenv
telebot                →  pyTelegramBotAPI
telegram               →  python-telegram-bot
PIL                    →  Pillow
bs4                    →  beautifulsoup4
yaml                   →  PyYAML
dateutil               →  python-dateutil
psycopg2               →  psycopg2-binary

Если пакета нет в списке, найдите его на pypi.org: там в заголовке всегда настоящее имя для pip install.

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

1. Пройдитесь по всем import и from … import во всех файлах бота. Всё, что не входит в стандартную библиотеку Python (os, json, sqlite3, asyncio и т.п. ставить не нужно), должно быть в requirements.txt.
2. Запишите по одной библиотеке на строку, под настоящим именем пакета:

   aiogram>=3
   python-dotenv
   aiosqlite

3. Положите файл в корень репозитория, рядом с главным .py, закоммитьте и запушьте.
4. Проверьте себя локально в чистом окружении. Это ровно то, что делает сервер:

   python -m venv /tmp/check && source /tmp/check/bin/activate
   pip install -r requirements.txt
   python bot.py

   Если в чистом окружении бот запустился, на сервере тоже запустится.

А pip freeze?

pip freeze > requirements.txt работает, только если вы с самого начала вели проект в отдельном виртуальном окружении (venv). Если ставили всё в системный Python, freeze выгрузит вообще всё, что там когда-либо стояло: jupyter, pandas от другого проекта, пакеты под Windows. Половина не нужна, часть не соберётся на Linux. В таком случае проще руками выписать 3–5 библиотек, которые бот реально импортирует.

aiogram 2 или 3

Версии несовместимы. Код из старых туториалов (2021–2022) написан под aiogram 2. Его видно по from aiogram.utils import executor, executor.start_polling, aiogram.dispatcher. Если в requirements просто aiogram, поставится 3.x, и такой код упадёт с ModuleNotFoundError или ImportError. Два варианта:

• зафиксировать старую версию: aiogram==2.25.2;
• переписать бота под 3.x. Это дольше, но 2.x уже не развивается.

Или без всего этого

botdepo при деплое смотрит импорты в вашем коде. Если requirements.txt нет, он сам предлагает готовый список строк, а при ModuleNotFoundError прямо в логе пишет, какой пакет дописать. Задеплоить бота.

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