Ошибка externally-managed-environment означает, что системная установка Python находится под управлением пакетного менеджера операционной системы. pip отказывается менять ее файлы, чтобы обновление одной библиотеки не сломало системную программу.

Что проверяет pip

Стандарт PEP 668 описывает маркер EXTERNALLY-MANAGED. Если интерпретатор запущен вне виртуального окружения и такой маркер существует, установщик должен остановиться и подсказать безопасный путь.

Решение для проекта

python3 -m venv .venv
source .venv/bin/activate
python -m pip install package_name

На Debian или Ubuntu для создания окружения может потребоваться системный пакет python3-venv. После активации проверьте python -m pip --version. Путь должен вести внутрь .venv. Полная последовательность разобрана в статье про pip и виртуальные окружения.

Если устанавливается консольная программа

Для Black, Ruff, Poetry и других командных инструментов удобен pipx. Он создает отдельное окружение для приложения и добавляет его команду в пользовательский PATH.

Стоит ли применять –break-system-packages

Флаг намеренно называется предупреждающе. Он отключает защиту и разрешает pip менять внешне управляемое окружение. Для обычного проекта это плохой обмен: несколько секунд экономии создают риск конфликта с пакетами ОС. Используйте системный менеджер для системных компонентов, venv для библиотек проекта и pipx для самостоятельных CLI-программ.