macOS: pip — externally-managed-environment

#Почему это появилось

Начиная с Python 3.11–3.12 дистрибутивы (Homebrew, Debian, Ubuntu, Fedora) помечают свой интерпретатор как «управляемый извне» файлом EXTERNALLY-MANAGED. Это защита по стандарту PEP 668: если глобально поставить пакет через pip, он может перезаписать зависимости, на которые опираются системные программы (например, Homebrew-формулы, написанные на Python), и сломать их. Поэтому pip отказывается, пока вы не выберете безопасный способ.

#Как правильно

1. Для своего проекта используйте виртуальное окружениеНа macOS откройте Finder → «Программы» → «Утилиты» → «Терминал» и перейдите командой cd в папку своего проекта. Выполните python3 --version и python3 -m pip --version, чтобы увидеть версию и расположение интерпретатора. Если ошибка externally-managed-environment возникает при глобальной установке через Homebrew, предпочтительно изолировать зависимости проекта: python3 -m venv .venv, затем . .venv/bin/activate; установите нужный пакет командой python -m pip install ИМЯ_ПАКЕТА, заменив имя. Успех — пакет появляется в python -m pip show ИМЯ_ПАКЕТА. Если venv не создаётся, проверьте установку Python и возможность записи в папку проекта.
2. Для утилит командной строки используйте pipxЕсли устанавливаете самостоятельную командную утилиту, а не библиотеку проекта, можно использовать pipx: brew install pipx, затем pipx ensurepath и после открытия нового окна терминала pipx install ИМЯ_УТИЛИТЫ. Этот вариант предполагает, что Homebrew уже установлен и нужная утилита есть в PyPI; при отсутствии Homebrew следуйте официальной инструкции pipx, а не запускайте случайные команды установки. Проверьте pipx list; библиотеку для импорта через import в проекте устанавливайте в venv, а не через pipx.
3. Если пакет есть в HomebrewЕсли программа есть в каталоге Homebrew, поищите название пакета командой brew search ИМЯ и проверьте описание brew info ИМЯ, прежде чем выполнять brew install ИМЯ. Имена формул Homebrew и пакетов PyPI могут различаться; не предполагайте, что в Homebrew любой модуль называется python-имя. Установка через brew — альтернатива pipx или venv для подходящих программ, не обязательный третий шаг после них.
4. Для нескольких версий Python используйте pyenv или uvЕсли проект требует конкретную версию Python, сначала откройте pyproject.toml/README и посмотрите поддержку версий. С помощью официально установленного pyenv/uv можно выбрать изолированный интерпретатор, затем создать отдельное venv и убедиться в версиях python --version, python -m pip --version. Не меняйте системный python3 или ссылки /usr/bin/python3; это может нарушить инструменты macOS или менеджера пакетов. Для большинства проектов достаточно стандартного venv без дополнительных средств.
5. Не добавляйте --break-system-packagesПараметр --break-system-packages обходится без изоляции и может испортить пакеты, которыми управляет Homebrew/система. Не используйте его как штатное решение, не добавляйте в глобальный pip.conf. Если после создания venv ошибка сохраняется, выполните which python, python -m pip --version и убедитесь, что пути ведут внутрь .venv; возможно, терминал всё ещё вызывает чужой pip. Выйти из виртуального окружения можно командой deactivate.
6. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Создать окружение в проекте, включить и поставить пакеты

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

   Создать окружение в проекте, включить и поставить пакеты

   cd ~/projects/myapp

   python3 -m venv .venv

   source .venv/bin/activate

   python -m pip install requests

   Вариант 2Выйти из окружения; перед работой активируйте его снова

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

   Выйти из окружения; перед работой активируйте его снова

   deactivate

   Вариант 3Установка консольных утилит изолированно (pipx)

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

   Установка консольных утилит изолированно (pipx)

   brew install pipx

   pipx ensurepath

   pipx install httpie

   Вариант 4Альтернатива: менеджер uv быстро создаёт окружения и ставит пакеты

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

   Альтернатива: менеджер uv быстро создаёт окружения и ставит пакеты

   brew install uv

   uv venv

   source .venv/bin/activate

   uv pip install requests

   Вариант 5Проверка, какой Python используется и где он живёт

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

   Проверка, какой Python используется и где он живёт

   which python3

   python3 --version

   python3 -c "import sys; print(sys.prefix)"

   Вариант 6Сохранить зависимости проекта и восстановить на другом компьютере

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

   Сохранить зависимости проекта и восстановить на другом компьютере

   python -m pip freeze > requirements.txt

   python -m pip install -r requirements.txt

#Типичные ситуации

Если после активации окружения which python не указывает на .venv, проверьте, что команда source .venv/bin/activate выполнена в той же вкладке терминала, а в приглашении появился префикс (.venv). Папку .venv добавьте в .gitignore, так как её содержимое не переносится между компьютерами.