pip: error: externally-managed-environment — pip не ставит пакеты в Ubuntu
Ошибка значит, что pip отказался ставить библиотеку в системный Python: в Ubuntu 24.04 и 26.04 им управляет apt. Решение — виртуальное окружение приложения: выполните python3 -m venv venv, затем source venv/bin/activate и pip install имя_библиотеки. Ниже — шаги по порядку, другие способы и что делать, если ошибка осталась.
Содержание 14
- Как выглядит ошибка
- Почему pip отказывается
- Шаг 1. Создайте окружение
- Шаг 2. Включите окружение и поставьте библиотеку
- Окружение создано, а ошибка осталась
- Если нужна программа, а не библиотека
- Если библиотека есть в apt
- Какие команды дают ту же ошибку
- На Ubuntu 22.04 работало, а теперь ошибка
- Чего не делать
- Как проверить
- Ответы на вопросы
- Источники
- Что почитать дальше
Как выглядит ошибка
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
…
See /usr/share/doc/python3.12/README.venv for more information.
note: If you believe this is a mistake, … by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.В Ubuntu 26.04 вместо python3.12 будет python3.14. Текст после стрелки pip берёт из файла EXTERNALLY-MANAGED, который кладёт Ubuntu. Тексты сверены с исходным кодом pip 24.0 из пакетов Ubuntu 24.04 и pip 25.1.1 из пакетов Ubuntu 26.04.
Почему pip отказывается
Python в Ubuntu нужен самой системе: на нём написаны её программы, а его библиотеками управляет apt. В папке /usr/lib/python3.12/ (в 26.04 — /usr/lib/python3.14/) лежит файл-метка EXTERNALLY-MANAGED. Увидев его, pip не ставит пакеты в системный Python и предлагает три пути. Какой выбрать:
| Что ставите | Как ставить |
|---|---|
| библиотеку для своего приложения или бота | в окружение venv — шаги ниже |
| программу, которую запускаете командой | через pipx — раздел ниже |
| библиотеку для скрипта, который работает на системном Python | через apt — раздел ниже |
Шаг 1. Создайте окружение
Команды на этой странице вводятся на сервере: подключитесь к нему по SSH (как подключиться) и набирайте их в том же окне.
Перейдите в папку приложения и создайте окружение в подпапке venv:
cd /home/ivan/myapp
python3 -m venv venvЕсли команда пишет ensurepip is not available, сначала поставьте пакет python3-venv — разбор этой ошибки.
Шаг 2. Включите окружение и поставьте библиотеку
source venv/bin/activate
pip install requestsВ начале строки ввода появится (venv): теперь pip ставит библиотеки в папку окружения, и ошибки не будет. Если у приложения есть requirements.txt — pip install -r requirements.txt.
Включать окружение для запуска не обязательно: Python окружения можно вызвать по полному пути, /home/ivan/myapp/venv/bin/python app.py. Этот же путь указывают в службе systemd (как запустить приложение службой).
Окружение создано, а ошибка осталась
Значит, команда попала к системному pip, а не к pip окружения. Причин три:
| Что видно | В чём дело | Что сделать |
|---|---|---|
в начале строки ввода нет (venv) | окружение не включено: в каждом новом окне SSH его включают заново | выполните source venv/bin/activate в папке приложения |
команда начинается с sudo | в Ubuntu 24.04 sudo ищет команду в системных папках и находит системный pip, а не pip окружения | уберите sudo: в своей папке права администратора не нужны |
| pip вызывает скрипт, cron или служба | окружение там не включено | укажите полный путь: /home/ivan/myapp/venv/bin/pip install requests |
Если нужна программа, а не библиотека
Программы на Python, которые запускают командой, удобно ставить через pipx: он сам создаёт для каждой программы отдельное окружение.
sudo apt install pipx
pipx ensurepath
pipx install httpieЕсли система спросит пароль, введите пароль своего пользователя на сервере. Символы при вводе не видны — так и должно быть: наберите пароль и нажмите Enter. На вопрос Do you want to continue? [Y/n] нажмите Y и Enter. Команда pipx ensurepath добавляет папку с программами pipx в путь поиска команд (переменная PATH). Откройте новое окно SSH, и программа запустится по имени.
Если библиотека есть в apt
Для скриптов, которые работают на системном Python, библиотеку ставят из пакетов Ubuntu. Имя пакета — python3- и имя библиотеки:
sudo apt install python3-requestsЕсли apt пишет Unable to locate package, такого пакета нет — разбор. Тогда ставьте библиотеку в окружение venv.
Какие команды дают ту же ошибку
pip проверяет метку перед установкой и перед удалением пакетов. Вне окружения ошибкой закончатся все эти команды:
| Команда | Почему не помогает |
|---|---|
pip3 install requests, python3 -m pip install requests | это тот же pip системного Python |
sudo pip install requests | метка действует для любого пользователя, для root тоже |
pip install --user requests | ключ --user проверку не отключает |
pip install --upgrade pip | системный pip обновляет apt вместе с пакетом python3-pip |
pip uninstall requests | удалять пакеты из системного Python pip тоже отказывается |
Команды, которые ничего не ставят и не удаляют, работают и без окружения: pip list, pip show requests, pip --version.
На Ubuntu 22.04 работало, а теперь ошибка
В пакетах Python из Ubuntu 22.04 файла-метки нет, поэтому там pip ставил библиотеки без этой проверки. В Ubuntu 24.04 и 26.04 метка есть, и старые инструкции и скрипты установки с pip install или sudo pip install останавливаются на этой ошибке. Исправление то же: создайте окружение и замените в скрипте pip на полный путь к pip окружения — /home/ivan/myapp/venv/bin/pip.
Чего не делать
Не ставьте библиотеки через sudo pip и не добавляйте ключ, который pip упоминает в строке note. Чужая версия библиотеки в системном Python может сломать программы Ubuntu, написанные на Python.
Как проверить
which pipВо включённом окружении ответ — путь внутри папки venv, например /home/ivan/myapp/venv/bin/pip. Значит, pip ставит библиотеки в окружение.
Ответы на вопросы
Можно ли удалить файл EXTERNALLY-MANAGED? Не стоит. Файл входит в пакет libpython3.12-stdlib (в Ubuntu 26.04 — libpython3.14-stdlib) и вернётся при обновлении этого пакета. А библиотеки, поставленные за это время мимо apt, останутся в системном Python и могут помешать программам Ubuntu.
Нужно ли включать окружение каждый раз? Для установки библиотек — да: в новом окне SSH выполните source venv/bin/activate. Для запуска приложения включать окружение не нужно: вызывайте Python по полному пути, /home/ivan/myapp/venv/bin/python.
Куда pip ставит библиотеки в окружении? В папку venv/lib/python3.12/site-packages внутри приложения (в Ubuntu 26.04 — python3.14). Системный Python эти библиотеки не видит, поэтому у каждого приложения может быть своя версия одной и той же библиотеки.
Можно ли скопировать папку venv на другой сервер? Нет: в файлах окружения записаны полные пути этого сервера. Сохраните список библиотек командой pip freeze > requirements.txt, на новом сервере создайте окружение заново и выполните pip install -r requirements.txt.
Источники
- Ubuntu 24.04: файл EXTERNALLY-MANAGED.in из пакета python3.12 — текст после стрелки.
- Ubuntu 26.04: тот же файл из пакета python3.14.
- Исходный код pip 24.0: exceptions.py — строки error, note и hint.
- Исходный код pip 24.0: команда install — когда pip проверяет метку: ключ --user проверку не отключает.
- Исходный код pip 24.0: команда uninstall — та же проверка перед удалением.
- Ubuntu 24.04: файлы пакета libpython3.12-stdlib — в списке есть EXTERNALLY-MANAGED; в пакете Python из Ubuntu 22.04 его нет.
- PEP 668 — как работает метка EXTERNALLY-MANAGED.
- Документация Python: venv — на английском: почему окружение не переносят копированием.
- Ubuntu 24.04: файл sudoers из пакета sudo — строка secure_path: в каких папках sudo ищет команды.
Сверено 22 октября 2026 года; команды с той же ошибкой, Ubuntu 22.04 и ответы на вопросы — 15 ноября 2026 года.
Что почитать дальше
- Python, pip и venv на Ubuntu.
- ModuleNotFoundError: No module named.
- ensurepip is not available.
- Все ошибки Python и pipтаблица по тексту сообщения.