Python venv, pipx или uv: что выбрать для сервера
Ошибка externally-managed-environment блокирует pip install на Ubuntu 24.04. Узнайте, когда использовать venv, pipx или uv для управления зависимостями и настройки systemd.
Почему pip install завершается ошибкой на новом сервере Ubuntu
Выбор между Python venv, pipx и uv на сервере зависит от одного вопроса: что именно вы устанавливаете? Зависимости приложения должны находиться в виртуальном окружении внутри каталога самого приложения. Инструменты командной строки, которые нужно запускать по имени, следует устанавливать через pipx. uv выполняет обе задачи и дополнительно использует lockfile. Это становится важно, как только второй компьютер должен собрать такое же окружение. Ни один из этих инструментов не устанавливает пакеты в системный Python, потому что современный сервер Ubuntu напрямую запрещает это.
Запустите sudo pip install requests в Ubuntu 24.04, и pip завершит работу до загрузки хотя бы одного файла.
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.
If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip.
If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.Так работает PEP 668 (предложение по улучшению Python 668, «externally managed environments»). Debian и Ubuntu помещают рядом с интерпретатором файл-маркер в /usr/lib/python3.12/EXTERNALLY-MANAGED, и pip отказывается записывать данные в любой интерпретатор, для которого существует такой файл.
Это правило связано с порядком sys.path. apt устанавливает библиотеки в /usr/lib/python3/dist-packages. Если запустить pip от имени root для системного интерпретатора, он записывает данные в /usr/local/lib/python3.12/dist-packages, а система упаковки Debian помещает этот каталог раньше в порядок поиска. Проверьте это самостоятельно с помощью python3 -c 'import sys; print(sys.path)' и прочитайте порядок. Поэтому копия, записанная pip, перекрывает копию, установленную apt, для каждой программы на сервере, которая работает под управлением /usr/bin/python3, включая собственные инструменты дистрибутива. cloud-init импортирует requests, jinja2 и PyYAML из этого интерпретатора. Обновите одну из этих библиотек через pip, получите несовместимую версию, и при следующей загрузке перестанет работать компонент, которого вы не изменяли. В traceback будет указано имя пакета, о наличии которого в этой цепочке вы могли не знать. apt по-прежнему считает установленной свою версию, поэтому предупреждение не появляется. Для исправления удалите копию pip с помощью sudo pip uninstall --break-system-packages requests, поскольку sudo apt reinstall python3-requests без дополнительных действий только перезаписывает копию apt, которая уже была перекрыта.
Следующее правило простое. Системный Python принадлежит дистрибутиву. Не устанавливайте в него пакеты, не обновляйте его библиотеки с помощью pip и не удаляйте файл EXTERNALLY-MANAGED, чтобы скрыть сообщение. Единственная задача для /usr/bin/python3 — создание виртуальных окружений.
venv, pipx или uv: правила выбора
Выбирайте инструмент в зависимости от того, что именно вы устанавливаете, а не от того, о чем прочитали в последнее время.
- Приложение, которое вы разворачиваете и запускаете как сервис, например проект на Django или Flask: используйте одну виртуальную среду (venv) внутри каталога этого приложения.
- Инструмент командной строки, который должен быть доступен в вашем
PATH, напримерansibleилиhttpie: используйте pipx, который создает для каждого инструмента изолированную среду и одну ссылку вPATH. - Проект, которому требуется файл блокировки (lockfile), ускоренная установка или версия Python, отсутствующая в дистрибутиве: используйте uv, который создает обычную venv и файл
uv.lock. - Библиотека, необходимая системному инструменту, а не вашему коду: используйте
sudo apt install python3-<name>— это единственный поддерживаемый способ добавления чего-либо в системный интерпретатор.
Инструменты pipx и uv tool install выполняют одну и ту же задачу, поэтому на сервере, где уже есть uv, устанавливать pipx не требуется. Выбор веб-фреймворка здесь ничего не меняет: Django и Flask на VPS различаются тем, что именно попадает в requirements.txt, а не способом построения окружения вокруг них. Все примеры ниже используют Ubuntu 24.04 и встроенный Python 3.12, поэтому при необходимости скорректируйте версии в путях.
Создайте отдельное venv для приложения
Ubuntu выносит модуль venv из базового пакета Python. Поэтому первая попытка на минимальном образе завершается сообщением с точным указанием отсутствующего компонента.
The virtual environment was not created successfully because ensurepip is not
available. On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.
apt install python3.12-venvУстановите его. Затем создайте окружение от имени пользователя, которому будет принадлежать код.
sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txtОбратите внимание, чего здесь нет: ни source, ни activate. /srv/myapp/.venv/bin/pip устанавливается в это окружение из-за расположения бинарного файла, а не из-за переменных, экспортированных в shell. Проверьте это, прежде чем продолжать.
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'Команда выводит /srv/myapp/.venv. Если она выводит /usr, вы используете системный интерпретатор, а пакеты установлены не туда, куда требовалось.
Два свойства venv определяют, что с ним можно делать дальше. Venv нельзя перемещать, потому что каждый скрипт точки входа в bin/ содержит абсолютную shebang-строку: head -1 /srv/myapp/.venv/bin/pip читает #!/srv/myapp/.venv/bin/python. Если переименовать родительский каталог, эти скрипты завершаются с ошибкой bad interpreter: No such file or directory. Venv также фиксирует интерпретатор, которым он был создан. Эта информация записана в строке home файла /srv/myapp/.venv/pyvenv.cfg, а bin/python3 является символической ссылкой на /usr/bin/python3. Обновите выпуск так, чтобы этот путь указывал на более новую версию Python. Тогда новый интерпретатор будет искать пакеты в каталоге lib/python3.13, которого нет в venv, и сервис завершится при запуске с ошибкой ModuleNotFoundError. В обоих случаях решение одинаковое: удалите venv и создайте его заново из requirements.txt. Пересоздание занимает несколько секунд. Никогда не копируйте venv между машинами.
Где размещать venv и кто должен быть его владельцем
Размещайте виртуальное окружение рядом с кодом в /srv/myapp/.venv и используйте отдельный venv для каждого приложения. В этом случае развертывание представляет собой единый каталог, systemd-юнит получает неизменяемый путь, а два приложения не смогут нарушить работу друг друга при обновлении общих зависимостей. Не размещайте venv в директориях, которые ваш веб-сервер публикует напрямую, так как там хранятся зависимости и часто конфигурационные файлы.
Вопрос прав владения требует внимания. Пусть пользователь deploy владеет кодом и окружением, а сервисной учетной записи предоставьте только права на чтение и выполнение.
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappТеперь сервис может импортировать свои зависимости, но не может их изменять. Это означает, что ошибка выполнения кода в веб-приложении не позволит злоумышленнику незаметно заменить библиотеку на диске и сохранить изменения после перезагрузки. Тот же подход к остальным частям системы описан в запуск сервисов от имени пользователей с минимальными привилегиями.
pipx для инструментов командной строки
pipx устанавливает приложения, а не библиотеки. Каждая утилита получает собственное окружение в ~/.local/share/pipx/venvs/<name>, а исполняемые файлы этой утилиты создаются в виде ссылок в ~/.local/bin. Поэтому две утилиты, которым нужны разные версии одной библиотеки, не конфликтуют.
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx ensurepath добавляет ~/.local/bin в PATH, изменяя файл запуска оболочки. Уже открытая оболочка не изменяется. Поэтому сообщение http: command not found сразу после установки обычно означает, что вы ещё не вышли из системы и не вошли снова. Ubuntu добавляет ~/.local/bin в стандартный ~/.profile только в том случае, если этот каталог уже существует во время входа в систему. Поэтому при создании новой учётной записи проблема возникает один раз и больше не повторяется.
Если указать pipx библиотеку, он откажется её устанавливать и выведет сообщение, начинающееся так:
No apps associated with package requests.Это означает, что pipx не подходит для данной задачи. Библиотеки должны находиться в venv приложения.
На сервере важно, где установлена утилита. Обычная команда pipx install размещает всё в домашнем каталоге одного пользователя. Сервис systemd, запущенный от имени myapp, не увидит эту установку. Её также не увидит задание cron от имени root, и sudo не найдёт её, потому что secure_path в /etc/sudoers заменяет PATH фиксированным списком. Если утилита нужна всей системе, установите её глобально.
sudo pipx install --global ansible
sudo pipx ensurepath --globalФлаг --global размещает окружения в /opt/pipx, а исполняемые файлы — в /usr/local/bin. Этот каталог входит в стандартный PATH и находится внутри secure_path. Сначала проверьте версию командой pipx --version. В Ubuntu 24.04 доступен pipx 1.4.3, который старше версии --global, поэтому более старый pipx выводит unrecognized arguments: --global. В этой версии задайте два документированных каталога вручную:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansibleКоманда command -v ansible должна вывести /usr/local/bin/ansible. Если она выводит путь внутри /home, утилита установлена в учётной записи одного пользователя, и ни один сервис её не найдёт.
uv, если нужен lockfile
uv — это единый бинарный файл от Astral. Он объединяет возможности pip, venv и pip-tools, а также умеет загружать интерпретаторы. Он достаточно быстрый, чтобы это было заметно на небольшом VPS, и создаёт полноценный lockfile.
Официальный установщик размещает uv и uvx в ~/.local/bin:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionПеред передачей скрипта в shell на сервере стоит принять меры предосторожности. Зафиксируйте версию в URL и прочитайте файл до его запуска:
curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.shpipx install uv тоже работает, если pipx уже установлен. uv — это один автономный бинарный файл без собственной зависимости от Python. Поэтому его можно скопировать в /usr/local/bin и сделать доступным всем пользователям системы.
Для проекта с pyproject.toml рабочий процесс состоит из четырёх команд. Только последняя команда выполняется на сервере.
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devuv lock записывает uv.lock — кроссплатформенный lockfile с точными разрешёнными версиями. Его следует зафиксировать в репозитории рядом с исходным кодом. uv sync создаёт .venv в корневом каталоге проекта в соответствии с ним. На сервере важен флаг --frozen. В документации указано, что он использует версии из lockfile как источник истины, не проверяя, актуален ли lockfile. Именно такое поведение требуется при развёртывании. --no-dev исключает группу зависимостей для разработки.
Для существующего проекта requirements.txt преобразование не требуется, поскольку uv поддерживает формат pip:
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtВ результате создаётся обычное виртуальное окружение с одним отличием: uv не устанавливает в него pip. Поэтому .venv/bin/pip и .venv/bin/python -m pip не работают, если окружение создано без uv venv --seed. Вместо этого установите зависимости с помощью uv pip. Далее в этом руководстве pip внутри окружения не используется, поэтому последующие шаги не меняются.
Перед использованием uv на сервере стоит знать об одном его значении по умолчанию. Параметр python-preference по умолчанию имеет значение managed. В документации указано, что это значение выбирает «интерпретаторы, загруженные и установленные uv», а не интерпретаторы, уже присутствующие в системе. Поэтому uv venv --python 3.13 на сервере, где установлен только 3.12, без предупреждения загрузит 3.13 в ~/.local/share/uv/python, вместо того чтобы завершиться с ошибкой. На рабочем компьютере это удобно, но на сервере может привести к неожиданным последствиям: сервис начнёт использовать интерпретатор из домашнего каталога, который apt upgrade никогда не обновит. Установите python-preference в значение only-system в uv.toml, если хотите использовать интерпретатор из дистрибутива. Если окружение должно находиться не в корневом каталоге проекта, UV_PROJECT_ENVIRONMENT задаёт каталог для виртуального окружения проекта.
Указывайте в systemd путь к интерпретатору venv, а не к скрипту activate
Здесь ломается большинство развертываний Python, так как администраторы неверно понимают назначение activate.
bin/activate — это shell-скрипт. Он добавляет директорию bin виртуального окружения в начало PATH, устанавливает VIRTUAL_ENV, сохраняет старые значения для возможности отката через deactivate и меняет вид приглашения командной строки. В нем нет ничего, что считывал бы сам интерпретатор. Активация — это лишь удобство для человека, который вводит python в терминале.
Выбор окружения определяется тем, какой именно файл интерпретатора вы запускаете. При запуске /srv/myapp/.venv/bin/python модуль site в Python ищет файл pyvenv.cfg в директории с исполняемым файлом или уровнем выше. Обнаружение /srv/myapp/.venv/pyvenv.cfg устанавливает sys.prefix на путь к venv, что добавляет site-packages этого окружения в sys.path. Это весь механизм работы. Ему не нужны переменные окружения или оболочка.
Поэтому такой юнит не запустится:
[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:appmyapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXECExecStart — это не командная строка shell. systemd запускает программу напрямую, поэтому встроенная команда source отсутствует, && передается как буквальный аргумент, а раскрытие переменных оболочки не происходит (за исключением тех немногих, что документированы в самом systemd).
А такой юнит запустится и сразу завершится:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 — это системный интерпретатор, и в его sys.path никогда не было вашего venv. Та же команда работает в вашей SSH-сессии только потому, что вы активировали там venv, и оболочка разрешила python3 через PATH в .venv/bin/python3.
Обертывание команды в /bin/bash -c 'source ... && gunicorn ...' работает. Однако это создает лишнюю прослойку в виде shell между systemd и вашим процессом без какой-либо пользы, в то время как использование абсолютного пути решает проблему:
[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pagersystemctl status myapp должен выводить active (running) с Main PID, соответствующим вашему процессу gunicorn. Если вывод иной — читайте журнал.
Строка Environment=PATH= нужна не для ExecStart, так как там уже указан полный путь. Она нужна для процессов, которые запускает ваше приложение. Сервис наследует короткий стандартный PATH от systemd, поэтому Python-код, вызывающий subprocess.run(["ffmpeg", ...]), или команда управления, обращающаяся к консольному скрипту из venv, не найдут нужных файлов. Добавление директории bin вашего venv в начало — это единственная часть activate, которая действительно используется сервисом. Проверьте, что именно получил юнит, с помощью systemctl show -p Environment myapp.
Это же правило касается и запланированных задач. В Ubuntu cron не передает задаче PATH из вашей оболочки или демона: если в crontab не задан PATH, каждая задача получает скомпилированный по умолчанию /usr/bin:/bin, а /etc/environment его не переопределяет. В нем нет вашего venv, поэтому строка в crontab вида python3 /srv/myapp/cleanup.py запускает системный интерпретатор и завершается с ошибкой ModuleNotFoundError в три часа ночи. cron отправляет ошибку владельцу crontab или на адрес MAILTO, если он задан, что на большинстве серверов означает локальный почтовый ящик, который никто не читает. Если почтовая программа не установлена, cron отбрасывает вывод и записывает только No MTA installed, discarding output в системный лог. Указывайте абсолютный путь к venv и там. Чтобы получать этот вывод в журнале и иметь запись о последнем запуске, используйте пару из systemd-сервиса и таймера, которая принимает ту же строку ExecStart.
Заменяет ли Docker это решение?
Контейнер имеет собственную файловую систему, поэтому вопрос меняет форму, но не исчезает. В официальном образе, таком как python:3.12-slim, Python встроен в /usr/local и не содержит маркера EXTERNALLY-MANAGED, поэтому pip install от имени root является штатным способом добавления пакетов, а venv в данном случае почти ничего не дает. Если вы собираете FROM ubuntu:24.04 самостоятельно, вы снова столкнетесь с externally-managed-environment внутри образа по той же причине, что и на хосте: это системный интерпретатор, содержащий маркерный файл дистрибутива.
Многие образы по-прежнему используют venv, так как это упрощает многоэтапную сборку (multi-stage build). Этап сборки устанавливает зависимости в /opt/venv, а этап выполнения копирует только этот каталог, оставляя компиляторы за бортом. Проблема активации перемещается вместе с ним. Строка RUN source /opt/venv/bin/activate влияет только на оболочку (shell) этого слоя сборки, поэтому при запуске контейнер начинает работу с системным интерпретатором и вызывает ModuleNotFoundError. Установите ENV PATH="/opt/venv/bin:$PATH" или укажите CMD абсолютный путь /opt/venv/bin/gunicorn. Это та же ошибка, что и в systemd, просто в другом файле.
Таким образом, контейнер заменяет вопрос об интерпретаторе, поскольку образ фиксирует версию интерпретатора и всего, что находится под ним. Он не заменяет вопрос о фиксации версий (pinning). Образ, собранный из незафиксированного requirements.txt, в следующем месяце может разрешить другие версии пакетов. Это означает, что тег образа воспроизводим, а процесс сборки, который его создал, — нет. Файл блокировки, такой как uv.lock, или полностью зафиксированный файл требований (requirements file) закрывает этот пробел, независимо от использования контейнеров. А когда одно приложение работает на одном VPS под управлением systemd, контейнер по большей части переносит это решение в Dockerfile, так как systemd и без того перезапускает упавший процесс и записывает его вывод в журнал. Запуск Docker на VPS оправдывает себя, когда вы хотите развертывать именно собранный образ.
FAQ
Можно ли просто выполнить pip install с --break-system-packages?
Нет, если сервер должен работать непрерывно. Этот флаг делает именно то, что указано: снимает защиту, и pip записывает пакеты в /usr/local/lib/python3.12/dist-packages, который находится раньше каталога apt в sys.path. После этого ваша версия имеет приоритет над версией дистрибутива для всех системных скриптов, выполняющихся под /usr/bin/python3. При этом apt по-прежнему считает установленной свою версию. Поэтому конфликт не обнаруживается, пока что-либо не перестанет работать. В образе контейнера, который каждый раз собирается с нуля, изменения затрагивают только этот образ, поэтому такой подход допустим. На обслуживаемой машине создайте venv. Для этого нужна одна команда.
Где должен находиться виртуальный environment на сервере?
В собственном каталоге приложения, например в /srv/myapp/.venv. Каталог должен принадлежать пользователю deploy, а учётная запись сервиса должна иметь только права на чтение и выполнение. Используйте отдельный venv для каждого приложения. Общий venv означает, что обновление первого приложения может нарушить работу второго. Не перемещайте и не копируйте venv после создания. Каждый скрипт entry point в его каталоге bin/ содержит этот абсолютный путь в строке shebang, поэтому после перемещения venv завершается с ошибкой bad interpreter: No such file or directory. Вместо этого удалите его и заново создайте из requirements.txt.
Почему мой сервис systemd завершается с ошибкой ModuleNotFoundError?
Потому что unit запускает не тот интерпретатор, который находится в venv. Выполните systemctl cat myapp и прочитайте ExecStart. Там должен быть указан /srv/myapp/.venv/bin/python или console script из того же каталога bin/, причём с абсолютным путём. Нельзя напрямую выполнять source activate в ExecStart, потому что ExecStart не является shell, а systemd сообщает об ошибке Failed to locate executable source с помощью status=203/EXEC. Добавьте Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin, чтобы любой subprocess, запускаемый вашим кодом, также находил инструменты из venv.
Следует ли использовать uv вместо venv и pip?
Используйте uv, если нужен lockfile, если установка занимает достаточно много времени или если требуется версия Python, которую ваш дистрибутив не выпускает. uv создаёт обычный venv, поэтому unit systemd и структура файлов не меняются, а uv sync --frozen устанавливает ровно то, что записано в lockfile. Если одно приложение разворачивается из git с закреплённым requirements.txt, а установка занимает несколько секунд, python3 -m venv уже достаточно. Кроме того, на сервере требуется обновлять на один бинарный файл меньше.