ModuleNotFoundError: No module named 'pandas' в FastAPI на Raspberry Pi — что не так с venv и запуском uvicorn

Как исправить ModuleNotFoundError: No module named 'pandas' при запуске FastAPI с uvicorn на Raspberry Pi: причина в venv/pip, даем пошаговое решение быстро.

Запуск сервиса FastAPI с uvicorn и multiprocessing на Raspberry Pi может обернуться на вид простейшей ошибкой: ModuleNotFoundError: No module named 'pandas'. В проекте используется отдельное виртуальное окружение, в списке зависимостей есть pandas, но импорт всё равно падает, когда uvicorn подгружает модуль приложения. Обычно проблема не в самом pandas и не в вашем коде, а в том, куда пакет был установлен и какой интерпретатор Python фактически запускает процессы.

Минимальное воспроизведение из пути сервиса

Сбой возникает в момент, когда uvicorn импортирует модуль приложения. В этом случае одной строки импорта достаточно, чтобы всё упало:

# src/services/ALS_back.py
import pandas as pnd

А запуск сервиса происходит из функции, которая передаёт управление uvicorn. Суть цепочки вызовов выглядит так:

# main.py
import uvicorn
def start_backend(port_num):
    uvicorn.run("src.services.ALS_back:app", host="0.0.0.0", port=port_num, reload=False)

Когда uvicorn доходит до импорта модуля, он выбрасывает ModuleNotFoundError для pandas.

Что на самом деле происходит не так

Трассировка показывает, что интерпретатор подхватывает пакеты из .venv проекта. При этом путь установки pip ведёт в /home/rpi/.local/lib/python3.9/site-packages — за пределами этого venv. Такое расхождение почти всегда означает, что пакеты ставили системным pip, а не тем, что принадлежит виртуальному окружению. Если ваш стартовый скрипт запускает Python, не активировав предварительно .venv проекта, порождённые процессы и рабочие uvicorn унаследуют неверный интерпретатор, и импорт провалится, даже если pandas установлен где-то ещё на диске.

Решение: устанавливайте пакеты в тот venv, под которым вы запускаетесь

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

cd /home/rpi/Desktop/als-v4
. .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-rpi.txt

После завершения проверьте, что пакеты подтягиваются из активного окружения:

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

Если приложение запускается через обёртку (например, alsv4), убедитесь, что перед вызовом Python или uvicorn она активирует .venv, чтобы все процессы работали под одним и тем же интерпретатором.

Когда «чистый лист» — самый быстрый путь

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

Почему это важно на Raspberry Pi и похожих системах

Такие инструменты, как uvicorn и multiprocessing, зависят от окружения, которое их запускает. Если ставить пакеты вне venv, а запускать в venv (или наоборот), вы получите ошибки импорта, даже когда пакет где-то в системе установлен. Жёсткое соблюдение принципа «установка и выполнение в одном .venv» избавляет от подобных сбоёв и делает развёртывание предсказуемым.

Итоги и практические рекомендации

Активируйте .venv проекта перед установкой пакетов и перед запуском приложения. Используйте python -m pip, чтобы привязать pip к текущему интерпретатору. Устанавливайте requirements-rpi.txt внутри этого venv. Проверяйте версии быстрыми импортами. Если проблемы тянутся из прошлых несоответствий, пересоздайте venv и переустановите зависимости. И, наконец, убедитесь, что стартовый скрипт включает окружение перед запуском uvicorn или рабочих процессов, чтобы все компоненты разрешали импорты из одного и того же места.