Как правильно устанавливать Python‑пакеты в Raspberry Pi OS Bookworm

Коротко о проблеме

Raspberry Pi OS Bookworm (основана на Debian Bookworm) ограничивает прямую установку Python‑пакетов в системную среду через pip. При попытке выполнить pip install вне виртуального окружения вы получите ошибку вида “externally‑managed‑environment” и подсказку использовать apt для системной установки. Это сделано, чтобы избежать конфликтов между pip и apt.

Важно: виртуальные окружения позволяют устанавливать любые версии библиотек без риска повредить системный Python. Все изменения внутри venv не влияют на систему.

Когда использовать apt, а когда pip в venv

• Используйте apt, если пакет доступен в репозиториях (например, python3-numpy). apt устанавливает пакеты в систему и обеспечивает обновление/безопасность через системный менеджер.
• Если пакета нет в репозитории или нужна более новая версия — создавайте виртуальное окружение и устанавливайте через pip внутри него.

Короткое правило: apt = системные зависимости, pip (в venv) = проектные зависимости.

Поиск и установка Python‑пакета через apt

1. Убедитесь, доступен ли пакет в репозитории:

apt search numpy

2. Установите системный пакет (для Python 3 пакеты обычно называются python3-<название>):

sudo apt update
sudo apt install python3-numpy

Используйте apt для библиотек, которые требуются всем пользователям системы или зависят от системных сервисов.

Создание и активация виртуального окружения (venv)

Если пакета нет в apt или нужна свежая версия, выполните следующие шаги.

1. Создайте окружение в каталоге вашего проекта (в примерах имя muo-project, но можно любое):

python3 -m venv muo-project

2. Перейдите в папку окружения и активируйте его (в стандартной структуре venv):

cd muo-project
source bin/activate

После активации приглашение оболочки будет содержать имя окружения, например (muo-project), — это знак, что вы используете Python внутри venv.

Совет: если вы используете fish или csh, команда активации отличается (source bin/activate.fish и т.д.).

Примечание: после перезагрузки систему нужно снова активировать окружение при новой сессии.

Копирование системных пакетов в venv

Если вам нужно, чтобы виртуальное окружение видело пакеты, установленные системно, создайте его с флагом –system-site-packages:

python3 -m venv --system-site-packages muo-project

Это даёт доступ к системным пакетам, но увеличивает риск конфликтов. Используйте этот режим осознанно.

Установка пакетов через pip внутри venv

После активации можно устанавливать пакеты локально:

pip install --upgrade pip
pip install stressberry

Команда pip установит пакет и его зависимости только в рамках текущего виртуального окружения.

Чтобы проверить установленные пакеты:

pip list

И чтобы выйти из окружения:

deactivate

Типичные ошибки и их исправления

• Ошибка: “externally-managed-environment”

  • Причина: вы запускали pip вне venv. Решение: создайте и активируйте venv или используйте apt для системной установки.

• Проблемы с правами доступа при установке в систему

  • Не пытайтесь решать их через sudo pip install — это может повредить пакеты, управляемые apt. Вместо этого используйте apt или venv.

• Портирование проектов между машинами

  • Экспортируйте зависимости в requirements.txt и восстанавливайте их в новом venv:

pip freeze > requirements.txt
pip install -r requirements.txt

Когда можно рассмотреть pipx или контейнеры

Для утилит, которые предназначены для запуска как самостоятельные команды (CLI), pipx — удобный вариант: он устанавливает пакеты в изолированную среду и делает их доступными глобально как команды. Для более крупного изоляции (системные зависимости, сервисы) лучше использовать контейнеры (Docker/Podman).

Мини‑методика: как подготовить проект Python на Raspberry Pi Bookworm (быстро)

1. Создайте папку проекта и перейдите в неё.
2. Создайте окружение: python3 -m venv .venv
3. Активируйте: source .venv/bin/activate
4. Обновите pip: pip install –upgrade pip
5. Установите зависимости: pip install -r requirements.txt или pip install
6. Запустите тесты, убедитесь, что всё работает.
7. Добавьте .venv в .gitignore, храните только requirements.txt в репозитории.

Контроль версий и стабильность

Держите системный Python и проектные зависимости отдельно. Для совместимости проектов указывайте минимальные и максимальные версии в requirements.txt или используйте poetry/poetry.lock для более строгого управления версиями.

Критерии приёмки

• venv создан и активирован без ошибок.
• pip install выполняется внутри окружения и пакет появляется в pip list.
• system python (python3) не изменён (пакеты, установленные через apt, остаются доступны).
• при деактивации окружения команда python возвращает системную версию.

Проверочный плейбук для трёх ролей

• Новичок:

  • Шаг 1: проверить apt search <пакет>
  • Шаг 2: если нет — создать venv и установить пакет внутри
  • Шаг 3: протестировать скрипт в активном окружении

• Разработчик:

  • Добавить .venv в .gitignore
  • Экспортировать зависимости в requirements.txt
  • Настроить pre-commit/CI для установки зависимостей из requirements.txt

• Системный администратор:

  • По возможности устанавливать общесистемные библиотеки через apt
  • Рекомендуется предоставить инструкции по локальным venv для пользователей

Рекомендации по безопасности и надёжности

• Не используйте sudo pip install в системной среде.
• Отдавайте предпочтение проверенным источникам пакетов.
• Для выполнения тестов и CI запускайте зависимости из чистого venv.

Ментальные модели и когда это не сработает

Модель: разделение ответственности — система (apt) vs проект (venv). Это работает в большинстве случаев. Не сработает, если вам нужно глобально заменить системную библиотеку, которая используется другими сервисами — в таком случае рассмотрите обновление через пакеты apt или контейнеризацию.

Диаграмма принятия решения

flowchart TD
  A[Нужен Python‑пакет?] --> B{Пакет в apt?}
  B -- Да --> C[Установить через apt 'sudo apt install python3-...']
  B -- Нет --> D{Требуется CLI‑утилита?}
  D -- Да --> E[Рассмотреть pipx или venv + распределить команду]
  D -- Нет --> F[Создать venv и pip install внутри него]
  E --> G[Проверить доступность команды в PATH]
  F --> H[Тестировать в активном окружении]

Краткая таблица команд (шпаргалка)

• Поиск: apt search <имя>
• Установка через apt: sudo apt update && sudo apt install python3-<имя>
• Создать venv: python3 -m venv venv
• Активировать: source venv/bin/activate
• Обновить pip: pip install –upgrade pip
• Установить пакет: pip install
• Сохранить зависимости: pip freeze > requirements.txt
• Выйти из venv: deactivate

Короткий глоссарий (1‑строчные определения)

• venv — встроенный модуль Python для создания изолированных окружений.
• pip — менеджер пакетов Python для установки библиотек в активную среду.
• apt — системный менеджер пакетов Debian/Ubuntu/Raspberry Pi OS.
• pipx — инструмент для установки CLI‑утилит в изолированные окружения и предоставления их как глобальных команд.

Заключение

Raspberry Pi OS Bookworm усиливает границу между системными и проектными зависимостями: apt остаётся инструментом для системного управления, а pip переносится в границы виртуальных окружений. Это повысит стабильность системы, если следовать простым практикам: сначала искать пакет в apt, затем — при необходимости — использовать venv и pip. Если потребуется глобальная утилита, рассмотрите pipx или контейнеризацию для более строгой изоляции.

Важно: всегда документируйте шаги установки для вашего проекта и храните список зависимостей в файле requirements.txt или lock‑файле менеджера зависимостей.