Python: error: externally-managed-environment

#Что означает ошибка

Ошибка externally-managed-environment появилась в Debian 12, Ubuntu 23.04+ и других дистрибутивах после внедрения PEP 668. Дистрибутив пометил системный Python как «управляемый извне» и запретил установку пакетов через pip в глобальное окружение, чтобы pip не конфликтовал с пакетами, поставленными менеджером apt, и не ломал системные утилиты, которые на Python написаны.

Раньше пользователи обходили ограничение флагом --break-system-packages, но это может привести к поломке системных инструментов. Правильные решения — виртуальное окружение, pipx для утилит командной строки и пакеты python3-* из репозитория.

Используйте виртуальное окружение или pipx вместо установки в системный Python.

#Причины и решения

#Пошаговое решение

1. Создайте виртуальное окружениеНа Debian/Ubuntu откройте терминал и выполните python3 --version и python3 -m pip --version. Если при python3 -m pip install ... появляется externally-managed-environment, системная среда управляется пакетным менеджером дистрибутива по правилам PEP 668. Перейдите в каталог своего проекта (cd /путь/к/проекту, заменив путь), проверьте pwd и выполните python3 -m venv .venv. Если модуль venv не установлен, администратор Debian/Ubuntu может установить python3-venv через sudo apt install python3-venv; это изменение системы нужно только для подготовки окружения.
2. Установите пакет внутри негоПосле успешного создания окружения в Linux/macOS выполните source .venv/bin/activate, затем python -m pip --version — путь должен указывать внутрь .venv. Теперь установите необходимый пакет, например python -m pip install requests, в том же терминале. Активация необязательна: эквивалентный способ — .venv/bin/python -m pip install requests. Если окружение не создаётся, проверьте владельца и разрешения каталога проекта и наличие места, не запускайте sudo pip и не используйте --break-system-packages.
3. Для утилит используйте pipxЕсли нужен не модуль проекта, а отдельная программа командной строки, используйте pipx как альтернативу venv. Для Debian/Ubuntu администратор может установить sudo apt install pipx, после чего обычный пользователь выполняет pipx ensurepath и открывает новый терминал. Затем, например, pipx install black устанавливает самостоятельную утилиту в изолированное окружение. Успех проверьте pipx list и командой программы black --version. Не устанавливайте через pipx библиотеку, которую ваш скрипт импортирует: для библиотек нужен проектный venv.
4. Системные пакетыЕсли библиотека требуется системной утилите, управляемой дистрибутивом, найдите официальный пакет через apt search python3-имя и сверяйте точное название с документацией системы; устанавливать его может администратор через apt. Это другой сценарий, чем разработка проекта внутри .venv. Не изменяйте файл EXTERNALLY-MANAGED и не используйте --break-system-packages: такое действие нарушает защиту системного Python. После выбора подходящего способа повторите импорт модуля внутри той среды, которая его должна использовать, например python -c 'import requests; print(requests.__version__)'.

#Виртуальное окружение

Для проектов создайте окружение: python3 -m venv .venv, активируйте его командой source .venv/bin/activate и устанавливайте пакеты через pip. Всё остаётся внутри папки проекта и никак не затрагивает систему. Если команда venv не найдена, установите пакет python3-venv.

#pipx для утилит

Программы командной строки (например, yt-dlp, black, httpie) ставьте через pipx: каждая получает собственное изолированное окружение, а команда становится доступной глобально. Установите pipx пакетом apt и выполните pipx install имя.

#Пакеты из репозитория

Некоторые библиотеки есть в apt под именем python3-имя. Они подходят, если вам нужна библиотека для системных скриптов. А флаг --break-system-packages допустим лишь в одноразовых контейнерах, где ломать нечего.

#Где скачать и что открыть

• Документация venv
• Скачать Python