pip: error: externally-managed-environment

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

Начиная с Python 3.11 в дистрибутивах (Debian 12, Ubuntu 23.04+, Fedora 38+, Arch, Homebrew) появился файл-маркер EXTERNALLY-MANAGED — по стандарту PEP 668. Он говорит pip: «этот Python принадлежит менеджеру пакетов системы, не ставь в него ничего». Установка командой pip install ломала бы системные пакеты, поэтому pip отказывается. Это не баг, а защита.

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

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

1. Установите поддержку venvЕсли при pip install появляется error: externally-managed-environment, это обычно защита системного Python, установленного менеджером пакетов Linux. Не считайте её поломкой pip. В терминале узнайте, какой Python используется: python3 --version и python3 -m pip --version; путь в сообщении указывает на системный интерпретатор. Для проекта не выполняйте sudo pip install и не удаляйте файл EXTERNALLY-MANAGED: так можно повредить приложения дистрибутива. Перейдите к отдельному виртуальному окружению. Перейдите в папку проекта командой cd (путь возьмите из Проводника/файлового менеджера). На Debian/Ubuntu, если команда создания окружения сообщила, что ensurepip отсутствует, установите системный пакет python3-venv через sudo apt update и sudo apt install python3-venv; потребуются права администратора. На других дистрибутивах имя пакета может отличаться — смотрите инструкции поставщика. Если установка запрещена на рабочем сервере, обратитесь к администратору вместо попытки обойти ограничение pip.
2. Создайте виртуальное окружениеВ папке проекта выполните python3 -m venv .venv. Команда создаёт новый каталог .venv с интерпретатором и инструментами установки. Убедитесь, что каталог появился (ls -a в Linux/macOS); если есть ошибка прав на директорию, выберите папку, где у вас есть доступ на запись, а не запускайте весь проект через sudo. Не копируйте .venv между компьютерами: для воспроизведения храните исходные зависимости отдельно.
3. Активируйте окружениеАктивируйте окружение для текущего терминала: Linux/macOS — source .venv/bin/activate, в PowerShell на Windows — .venv\Scripts\Activate.ps1, в CMD — .venv\Scripts\activate.bat. Увидите префикс (.venv) либо проверьте интерпретатор командой python -c "import sys; print(sys.prefix)". Если PowerShell блокирует запуск сценария, можно вообще не менять политику: используйте .venv\Scripts\python.exe -m pip .... Ошибка после активации обычно означает, что пакет ставится в другой Python.
4. Устанавливайте пакеты внутри окруженияУстановите нужный пакет из активированного окружения командой python -m pip install requests, заменив requests на зависимость проекта. Для проекта с готовым requirements.txt используйте python -m pip install -r requirements.txt; зависимости лучше брать из доверенного репозитория. Проверка: python -m pip show requests должен показать путь внутри .venv, затем запустите скрипт тем же python. При ошибке сети или сертификата решайте именно сетевую проблему, не используйте --trusted-host как общий обход.
5. Для консольных утилит используйте pipxЕсли требуется отдельная консольная программа, а не библиотека для проекта, используйте pipx, который ставит приложения в собственные окружения. На Debian/Ubuntu установка pipx может выполняться через sudo apt install pipx; затем без sudo выполните pipx ensurepath, переоткройте терминал и pipx install имя-программы для доверенной утилиты. Не устанавливайте через pipx библиотеку, которую импортирует ваше приложение: она не окажется в виртуальном окружении проекта.
6. Зафиксируйте зависимостиЗафиксируйте зависимости в файле проекта. Если уже есть requirements.txt с согласованными версиями — не перезаписывайте его без согласования; если проект новый, можно выполнить python -m pip freeze > requirements.txt в активном окружении. Проверьте содержимое файла и добавьте .venv/ в .gitignore, чтобы не публиковать установленные пакеты. На другом компьютере создайте новое окружение и установите зависимости из файла. Использование --break-system-packages допускается только при осознанном управлении изолированным окружением и не является рекомендуемым исправлением этой ошибки.
7. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Linux/macOS.

   Linux · Терминал (Bash)КомандаНужен sudoКопировать всёВыделить

   Linux/macOS. Первая команда нужна только при отсутствии venv и требует администратора, последующие — пользовательские. Для Windows используйте команды шага 4.

   # Debian/Ubuntu, установка поддержки окружений при необходимости:

   sudo apt install python3-venv

   # В папке проекта, без sudo:

   python3 -m venv .venv

   . .venv/bin/activate

   python -m pip install requests

   Вариант 2Команда с --break-system-packages приведена только как пример того, чего избегать на обычной системе.

   Linux · Терминал (Bash)Риск потери данныхКопировать всёВыделить

   Команда с --break-system-packages приведена только как пример того, чего избегать на обычной системе. Не выполняйте её; используйте окружение шага 3.

   # НЕ РЕКОМЕНДУЕТСЯ: установка в защищённый системный Python

   # python3 -m pip install --break-system-packages requests

   # Вместо неё используйте python3 -m venv .venv

   Эта команда может привести к потере данных или существенным изменениям. Проверьте параметры, резервную копию и возможность отката.