Uvicorn: Could not import module — проверяем путь к приложению

На ноутбуке команда uvicorn main:app запускает сервер. В контейнере или systemd тот же текст заканчивается «Could not import module». Кажется, что FastAPI не установлен или файл потерялся. Но сначала стоит разобрать сам адрес приложения: слева от двоеточия стоит Python-модуль, справа — объект внутри него.

main:app означает примерно «импортировать main и взять main.app». Поэтому на результат влияют структура пакетов, путь поиска модулей и выбранный интерпретатор.

Сначала воспроизведите импорт без сервера

Предположим, проект устроен так:

project/
  backend/
    __init__.py
    main.py

В backend/main.py находится app = FastAPI(). Из каталога project проверьте:

python -c "import backend.main; print(backend.main.app)"
python -m uvicorn backend.main:app

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

Запуск через python -m uvicorn связывает сервер с тем Python, которым вы только что проверяли импорт. Это полезно, когда команда uvicorn из PATH принадлежит другому виртуальному окружению.

Что делать со структурой src

Для структуры project/src/backend/main.py из корня можно явно указать каталог поиска:

python -m uvicorn backend.main:app --app-dir src

Значение --app-dir — каталог, а backend.main — имя модуля с точками. Это не путь к файлу, поэтому запись src/backend/main.py:app не заменяет корректный импорт.

Другой вариант для оформленного Python-пакета — установить проект в окружение и импортировать его как пакет. Выбор зависит от способа доставки приложения; важно, чтобы локальный запуск, тесты и контейнер использовали одну понятную структуру.

Проверка Docker и systemd

В Docker сопоставьте WORKDIR, COPY и команду запуска. Файл может оказаться в /app/backend/main.py, а запуск выполняться из /, где модуль backend не находится. В systemd посмотрите WorkingDirectory и абсолютный путь к Python виртуального окружения.

Не лечите ошибку копированием всех файлов в случайные каталоги и добавлением десятка путей в sys.path. Это скрывает устройство проекта и часто ломается при следующем деплое.

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

Если первый сервер ещё не запущен, начните с открытого урока: первый GET, Uvicorn и Swagger.

Собрать следующий этап проекта

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

Посмотреть программу: Python для продвинутых: ООП, типизация и тестирование

Проверить детали: Uvicorn: APP и app-dir, Python: поиск модулей.