Python на Raspberry Pi: с чего начать, Thonny, venv и ошибка externally-managed-environment

Python — главный язык для Raspberry Pi. На нём пишут программы для датчиков, умного дома, роботов и серверов, и он уже установлен в системе. Но почти каждый новичок упирается в одну и ту же ошибку, как только пытается поставить библиотеку командой pip install:

error: externally-managed-environment

× This environment is externally managed

Это не поломка. Система сознательно запрещает такой способ установки, и в статье мы разберём, почему и что делать вместо этого. Заодно настроим удобную среду для работы: выберем редактор, научимся запускать программы и работать с виртуальными окружениями (venv). Эта основа понадобится почти в каждой следующей статье, где используется Python: GPIO в Python, датчики, MQTT, метеостанция.

Статья написана для Raspberry Pi OS на базе Debian 13 «Trixie» (там Python 3.13) и Debian 12 «Bookworm» (Python 3.11). Те же приёмы работают на Orange Pi, Banana Pi и NanoPi с Armbian или Debian.

---

Python уже установлен

Проверьте версию:

python3 --version

В системе стоит Python 3. Разработчики предупреждают: системный Python нельзя «ломать», потому что на нём работают части самой операционной системы (например, графические утилиты Raspberry Pi). Поэтому библиотеки для своих проектов устанавливают особыми способами. Какими именно, объясним ниже.

Python 2. Он давно не поддерживается и в современной системе его нет. Команда python3 всегда запускает третью версию. В статьях сайта мы везде пишем именно python3, чтобы не путаться.

---

Первая программа

Самый простой способ: создать файл и запустить его. В терминале (по SSH или на самой плате) выполните:

nano hello.py

Откроется редактор nano. Введите одну строку:

print("Привет, Raspberry Pi!")

Сохраните файл (Ctrl+O, затем Enter) и закройте редактор (Ctrl+X). Запустите программу:

python3 hello.py

На экране появится Привет, Raspberry Pi!. Всё, вы написали первую программу.

---

Чем писать код

Редактор	Когда выбрать
Thonny	Лучший вариант для начала. Установлен в версии Raspberry Pi OS с рабочим столом. Есть кнопка запуска, отладчик и простой выбор интерпретатора
nano	Работа по SSH на версии Lite. Простой текстовый редактор, подсказки внизу экрана
Visual Studio Code	Удобный редактор для больших проектов. Лучше запускать на своём компьютере и подключаться к плате через расширение Remote-SSH
Любой редактор на компьютере	Пишете код на ПК, а на плату переносите файлы через scp или SFTP (подробнее в статье про SSH и SFTP)

Thonny

На Raspberry Pi OS с рабочим столом Thonny находится в меню Programming.

Нажмите зелёную кнопку Run (или клавишу F5), чтобы запустить программу. Результат появится в нижней панели Shell. Внизу справа Thonny показывает, какой интерпретатор Python используется: по умолчанию системный. При желании его можно сменить на виртуальное окружение (о нём ниже): меню интерпретатора → Configure interpreter….

Если у вас Lite-версия без рабочего стола, Thonny не нужен: пишите код в nano или на своём компьютере.

На снимке программа ещё не сохранена (вкладка <untitled>), поэтому Thonny запускает код прямо из редактора: в Shell видна служебная строка %Run -c $EDITOR_CONTENT, а под ней результат. Сохраните файл (Save), и вместо неё появится путь к файлу. Внизу справа указан интерпретатор /usr/bin/python3: это системный Python.

---

Откуда берутся ошибки при установке библиотек

Библиотеки для Python (датчики, MQTT, веб-серверы) можно поставить двумя способами.

• Через apt. Это системный менеджер пакетов. Пакеты для Python называются python3-что-то, например python3-numpy. Такие пакеты собраны специально для Raspberry Pi OS и ставятся быстро вместе со всеми зависимостями. Минус: выбор ограничен, версии бывают не самыми свежими.
• Через pip. Это менеджер библиотек самого Python. Там есть почти всё, и версии свежие. Но если ставить через pip в системный Python, возможен конфликт с пакетами apt.

Чтобы такие конфликты не ломали систему, сообщество Python приняло правило (PEP 668): в «управляемую системой» среду pip устанавливать нельзя. Поэтому, начиная с Raspberry Pi OS Bookworm, любая попытка выполнить pip install напрямую заканчивается ошибкой externally-managed-environment.

Не используйте —break-system-packages. Ошибку можно обойти флагом --break-system-packages. Но так вы рискуете сломать системные программы. Используйте виртуальное окружение: это не сложнее.

Итак, правило простое:

1. Если нужная библиотека есть в apt (python3-…), ставим её через apt.
2. Если её там нет, ставим через pip, но только в виртуальное окружение.

Способ 1. apt

Найти пакет можно поиском:

apt search python3- | grep -i gpiozero

Установка:

sudo apt install python3-gpiozero

Такая библиотека станет доступна всем программам Python в системе. Примеры из apt, которые нам пригодятся: python3-gpiozero, python3-picamera2, python3-numpy, python3-smbus2.

---

Виртуальное окружение (venv)

Виртуальное окружение — это отдельная папка, в которую устанавливаются библиотеки вашего проекта. Они не смешиваются с системными и не ломают систему. Для каждого проекта удобно делать своё окружение.

Создаём окружение

Создайте папку проекта и окружение внутри неё:

mkdir -p ~/monitor
cd ~/monitor
python3 -m venv env

Будет создана папка env. Если команда сообщает, что нужен пакет python3-venv, установите его: sudo apt install python3-venv.

Входим в окружение

source env/bin/activate

В начале строки появится (env): значит, вы внутри окружения. Теперь python3 и pip относятся к нему.

(env) admin@raspberrypi5:~/monitor $

Ставим библиотеки

pip install psutil

Библиотека установится в папку env. Список установленного покажет pip list. На Raspberry Pi pip обычно подключён к архиву piwheels: там лежат готовые сборки для Raspberry Pi, поэтому установка проходит быстро.

Выходим

deactivate

Так выглядят все шаги подряд: папка проекта, окружение, активация, установка psutil из архива piwheels и выход.

Запуск без входа в окружение

Чтобы запустить программу из окружения, не активируя его, вызывайте Python из папки env по полному пути:

~/monitor/env/bin/python3 ~/monitor/monitor.py

Этот способ потребуется, когда вы будете запускать программу автоматически, подробности в статье про автозапуск.

Окружение с доступом к системным пакетам

Некоторые библиотеки можно поставить только через apt: например, python3-picamera2 (камера), а часто и GPIO-библиотеки. Чтобы окружение видело такие пакеты, создайте его с ключом --system-site-packages:

python3 -m venv --system-site-packages env

В таком окружении доступны и системные пакеты, и те, что вы поставите через pip. Для проектов с датчиками и камерой это обычно самый удобный вариант.

Список зависимостей проекта

Сохраните, что установлено, чтобы повторить на другой плате:

pip freeze > requirements.txt

В нашем окружении установлена только psutil, поэтому в файле одна строка с точной версией (на вашей плате версия может отличаться). Открыть файл можно командой nano requirements.txt:

Установить всё по списку:

pip install -r requirements.txt

---

Практический пример: монитор платы

Соберём небольшую программу, которая показывает загрузку процессора, память и температуру. Откройте файл:

nano ~/monitor/monitor.py

import time

import psutil


def cpu_temp():
    # Температура процессора в градусах Цельсия
    with open("/sys/class/thermal/thermal_zone0/temp") as f:
        return int(f.read()) / 1000


while True:
    cpu = psutil.cpu_percent(interval=1)
    ram = psutil.virtual_memory().percent
    print(f"CPU: {cpu:5.1f} %   RAM: {ram:5.1f} %   Температура: {cpu_temp():.1f} °C")
    time.sleep(2)

Запустите программу в окружении:

cd ~/monitor
source env/bin/activate
python3 monitor.py

Остановить её можно сочетанием Ctrl+C. Результат будет примерно таким:

CPU:   3.0 %   RAM:  12.4 %   Температура: 46.2 °C
CPU:   1.0 %   RAM:  12.4 %   Температура: 46.7 °C

На снимке программа напечатала десять строк, после чего её остановили сочетанием Ctrl+C. Сообщение KeyboardInterrupt с трассировкой в этот момент нормально: Python сообщает, что работа прервана с клавиатуры. Чтобы оно не появлялось, можно перехватить исключение через try/except KeyboardInterrupt, но для такого простого монитора это не нужно.

---

Если что-то не работает

Проблема	Причина и решение
error: externally-managed-environment	Вы ставите через pip в системный Python. Создайте окружение (python3 -m venv env), активируйте его и повторите команду
ModuleNotFoundError: No module named …	Программа запущена не тем Python. Активируйте окружение, где вы ставили библиотеку, или запускайте по полному пути env/bin/python3
Библиотека установлена, но в окружении не видна	Для пакетов из apt создавайте окружение с --system-site-packages
python3 -m venv просит установить пакет	Выполните sudo apt install python3-venv
Программа работает вручную, а из sudo нет	sudo python3 запускает системный Python и не видит ваше окружение. Не используйте sudo для своих программ. Для GPIO и I2C он не нужен, достаточно, чтобы ваш пользователь входил в группы gpio и i2c (у обычного пользователя это так)
pip собирает библиотеку десятки минут или выдаёт ошибки компиляции	Для этого пакета нет готовой сборки. Проверьте, нет ли его в apt, или установите заголовочные файлы и компилятор по подсказке в ошибке
command not found: python	Используйте python3

---

Что дальше

• GPIO в Python: gpiozero — мигаем светодиодом и читаем кнопку.
• Автозапуск программ на Raspberry Pi — превращаем программу в службу.
• DHT22 и DHT11 на Raspberry Pi — первый датчик.
• Для работы с шиной I2C из Python посмотрите статью про SMBus.

---

Материалы

• Use Python on a Raspberry Pi — официальная документация: apt, pip и виртуальные окружения.
• PEP 668 — описание правила «externally managed environment».
• Thonny — сайт редактора.
• Документация модуля venv — официальное описание виртуальных окружений Python.
• piwheels — архив готовых сборок библиотек Python для Raspberry Pi.