Python no servidor: venv, pipx ou uv?
No Ubuntu 24.04, pip install falha com externally-managed-environment. Saiba quando usar venv, pipx ou uv e como apontar o systemd para o ambiente.
Por que pip install falha num servidor Ubuntu recém-instalado
A escolha entre um Python venv, pipx e uv num servidor depende de uma pergunta: o que está a instalar? As dependências de uma aplicação devem ficar num ambiente virtual dentro do diretório da própria aplicação. As ferramentas de linha de comandos que quer executar pelo nome devem ficar no pipx. uv faz as duas coisas e acrescenta um lockfile, que começa a ser importante assim que uma segunda máquina tem de criar o mesmo ambiente. Nenhuma destas ferramentas instala no Python do sistema, porque um servidor Ubuntu atual recusa essa operação.
Execute sudo pip install requests no Ubuntu 24.04 e pip termina antes de transferir um único ficheiro.
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.Isto é o PEP 668 (Python enhancement proposal 668, "externally managed environments") a funcionar como previsto. Debian e Ubuntu colocam um ficheiro marcador junto do interpretador, em /usr/lib/python3.12/EXTERNALLY-MANAGED, e pip recusa escrever em qualquer interpretador que contenha esse marcador.
A regra existe por causa da ordem de sys.path. apt instala bibliotecas em /usr/lib/python3/dist-packages. pip, executado como root contra o interpretador do sistema, escreve em /usr/local/lib/python3.12/dist-packages, e o sistema de pacotes do Debian coloca esse diretório mais cedo no caminho de pesquisa. Execute python3 -c 'import sys; print(sys.path)' para ver a ordem. Assim, a cópia escrita por pip sobrepõe-se à cópia instalada por apt em todos os programas do servidor que sejam executados com /usr/bin/python3, incluindo as próprias ferramentas da distribuição. cloud-init importa requests, jinja2 e PyYAML desse interpretador. Atualize uma dessas bibliotecas com pip, instale uma versão incompatível e algo que nunca alterou falhará no arranque seguinte, com um traceback que menciona um pacote cuja presença na cadeia de dependências desconhecia. apt continua a registar a sua própria versão como instalada, por isso nada o avisa. A correção consiste em remover a cópia de pip com sudo pip uninstall --break-system-packages requests, porque sudo apt reinstall python3-requests, por si só, apenas reescreve a cópia de apt que já estava a ser sobreposta.
A regra resultante é simples. O Python do sistema pertence à distribuição. Não instale nele, não atualize as respetivas bibliotecas com pip e não elimine o ficheiro EXTERNALLY-MANAGED para fazer desaparecer a mensagem. A única tarefa que deve atribuir a /usr/bin/python3 é criar ambientes virtuais.
venv vs pipx vs uv: regra de decisão
Escolha com base no que vai instalar, não na ferramenta sobre a qual leu mais recentemente.
- Uma aplicação que implementa e executa como serviço, como um projeto Django ou Flask: um ambiente virtual (venv) dentro do diretório dessa aplicação.
- Uma ferramenta de linha de comandos que quer em
PATH, comoansibleouhttpie: pipx, que atribui a cada ferramenta um ambiente privado e uma ligação emPATH. - Um projeto que precisa de um ficheiro de bloqueio, de instalações mais rápidas ou de uma versão do Python que a distribuição não disponibiliza: uv, que cria um venv normal e um ficheiro
uv.lock. - Uma biblioteca de que uma ferramenta da distribuição precisa, e não o seu código:
sudo apt install python3-<name>, a única forma suportada de adicionar algo ao interpretador do sistema.
pipx e uv tool install fazem o mesmo trabalho, por isso um sistema que já tem uv não precisa também de pipx. A framework web escolhida não altera nada neste ponto: Django e Flask num VPS diferem no que fica instalado em requirements.txt, não na forma como o ambiente envolvente é criado. Tudo abaixo usa o Ubuntu 24.04 e o respetivo Python 3.12, por isso ajuste a versão nos caminhos se a sua for diferente.
Crie o venv da aplicação
O Ubuntu separa o módulo venv do pacote base do Python. Por isso, numa imagem mínima, a primeira tentativa falha com uma mensagem que identifica exatamente o que está em falta.
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-venvInstale-o. Em seguida, crie o ambiente com o utilizador que será proprietário do código.
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.txtObserve o que não aparece: não há source nem activate. O /srv/myapp/.venv/bin/pip é instalado nesse ambiente devido à localização do binário, não por causa de algo que tenha exportado para a shell. Confirme isso antes de prosseguir.
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'Isto mostra /srv/myapp/.venv. Se mostrar /usr, está a executar o interpretador do sistema e os seus pacotes foram instalados num local que não pretendia.
Duas propriedades de um venv determinam o que pode fazer com ele depois. Um venv não é relocável, porque cada script de entry point em bin/ contém uma linha shebang absoluta: head -1 /srv/myapp/.venv/bin/pip lê #!/srv/myapp/.venv/bin/python. Se mudar o nome do diretório-pai, esses scripts falham com bad interpreter: No such file or directory. Um venv também fixa o interpretador que o criou. Essa informação fica registada como a linha home em /srv/myapp/.venv/pyvenv.cfg, e bin/python3 é um symlink para /usr/bin/python3. Atualize a versão de modo que esse caminho passe a apontar para um Python mais recente. O novo interpretador procurará então os pacotes num diretório lib/python3.13 que o venv não tem, e o serviço falhará ao iniciar com ModuleNotFoundError. Ambos os casos têm a mesma correção: elimine o venv e crie outro a partir de requirements.txt. A recriação demora segundos. Nunca copie um venv entre máquinas.
Onde fica o venv e quem é o proprietário
Coloque-o junto ao código em /srv/myapp/.venv e mantenha um venv por aplicação. O deployment passa a ser um único diretório, a unidade systemd recebe um caminho que nunca muda e duas aplicações nunca podem interferir uma com a outra através de uma atualização partilhada de dependências. Não coloque um venv num local onde o seu servidor web publique ficheiros diretamente, porque ele contém as dependências e, muitas vezes, a configuração.
A propriedade merece meio minuto de atenção. Faça com que um utilizador deploy seja o proprietário do código e do ambiente, e conceda à conta de serviço apenas permissões de leitura e execução.
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappO serviço pode agora importar as suas dependências, mas não pode reescrevê-las. Assim, uma falha de execução de código na aplicação web não pode substituir silenciosamente uma biblioteca no disco e persistir depois de um reinício. O mesmo princípio aplicado ao resto da máquina é abordado em executar serviços com utilizadores com privilégios mínimos.
pipx para ferramentas de linha de comandos
O pipx instala aplicações, não bibliotecas. Cada ferramenta recebe o seu próprio ambiente em ~/.local/share/pipx/venvs/<name>, e os executáveis dessa ferramenta são ligados em ~/.local/bin. Assim, duas ferramentas que precisam de versões diferentes da mesma biblioteca nunca entram em conflito.
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx ensurepath adiciona ~/.local/bin a PATH através da edição do ficheiro de arranque da shell. Não consegue alterar a shell que já está em execução. Por isso, http: command not found imediatamente depois da instalação normalmente significa que ainda não terminou a sessão e voltou a iniciar sessão. O ~/.profile predefinido do Ubuntu adiciona ~/.local/bin apenas quando esse diretório já existe no início da sessão. É por isso que este problema ocorre uma vez numa conta nova e nunca mais ocorre.
Se indicar uma biblioteca ao pipx, ele recusa a operação com uma mensagem que começa por:
No apps associated with package requests.A ferramenta está a indicar que este não é o instrumento correto. As bibliotecas devem ficar no venv de uma aplicação.
Num servidor, o local de instalação é o que importa. Um pipx install simples coloca tudo no diretório inicial de um utilizador. Uma unidade systemd executada como myapp não consegue aceder a esse conteúdo, uma tarefa cron do root também não, e sudo também não o encontrará, porque secure_path em /etc/sudoers substitui PATH por uma lista fixa. Para uma ferramenta que deve estar disponível em todo o sistema, instale-a globalmente.
sudo pipx install --global ansible
sudo pipx ensurepath --globalO sinalizador --global coloca os ambientes em /opt/pipx e liga os executáveis a /usr/local/bin. Esse diretório está no PATH predefinido e dentro de secure_path. Verifique primeiro a sua versão com pipx --version, porque o Ubuntu 24.04 fornece o pipx 1.4.3, que é mais antigo do que --global. Um pipx mais antigo responde com unrecognized arguments: --global. Nessa versão, defina manualmente os dois diretórios documentados:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansiblecommand -v ansible deve apresentar /usr/local/bin/ansible. Se apresentar um caminho dentro de /home, a ferramenta foi instalada na conta de um único utilizador e nenhum serviço a encontrará.
uv quando pretende um lockfile
uv é um único binário da Astral que cobre o que pip, venv e pip-tools fazem. Também pode descarregar interpretadores.
É suficientemente rápido para que a diferença seja percetível numa pequena VPS. Além disso, escreve um lockfile real.
O instalador oficial coloca uv e uvx em ~/.local/bin:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionExecutar um script enviado para uma shell num servidor exige alguma atenção. Fixe a versão no URL e leia o ficheiro antes de o executar:
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 também funciona quando pipx já está instalado. uv é um único binário autónomo, sem dependências próprias de Python. Por isso, copiá-lo para /usr/local/bin é uma forma válida de o disponibilizar a todos os utilizadores do sistema.
Num projeto com um pyproject.toml, o fluxo de trabalho consiste em quatro comandos. Apenas o último é executado no servidor.
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devuv lock escreve uv.lock, um lockfile multiplataforma que contém as versões exatas resolvidas. Deve fazer commit desse ficheiro juntamente com o código. uv sync cria .venv na raiz do projeto para corresponder a esse lockfile. No servidor, --frozen é a opção relevante. A documentação define-a como a utilização das versões presentes no lockfile como fonte de verdade, sem verificar se o lockfile está atualizado. Esse é o comportamento adequado numa implementação. --no-dev exclui o grupo de dependências de desenvolvimento.
Um projeto requirements.txt existente não precisa de conversão, porque uv é compatível com a sintaxe do pip:
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtO resultado é um ambiente virtual normal, com uma diferença: uv não instala pip nesse ambiente. Por isso, .venv/bin/pip e .venv/bin/python -m pip não funcionam, a menos que crie o ambiente com uv venv --seed. Em alternativa, instale com uv pip. Nenhum comando posterior deste guia executa pip dentro do ambiente. Portanto, nada mais precisa de ser alterado.
Há uma predefinição do uv que deve conhecer antes de o utilizar num servidor. A opção python-preference usa managed por predefinição. A documentação indica que isto dá prioridade aos interpretadores "descarregados e instalados pelo uv" em vez dos interpretadores já presentes no sistema. Assim, uv venv --python 3.13 num sistema que tenha apenas a versão 3.12 descarrega silenciosamente a versão 3.13 para ~/.local/share/uv/python em vez de falhar. Isto é conveniente num computador pessoal, mas pode ser inesperado num servidor, porque o serviço passa a depender de um interpretador localizado num diretório pessoal que apt upgrade nunca irá atualizar. Defina python-preference como only-system em uv.toml se pretender utilizar o interpretador da distribuição. Se pretender o ambiente num local diferente da raiz do projeto, UV_PROJECT_ENVIRONMENT especifica o diretório a utilizar para o ambiente virtual do projeto.
Aponte o systemd para o interpretador do venv, não para o activate
É aqui que a maioria das implementações Python falha. A causa é uma interpretação incorreta do que activate faz.
bin/activate é um script de shell. Ele coloca o diretório bin do venv no início de PATH, define VIRTUAL_ENV, guarda os valores anteriores para que deactivate os possa restaurar e altera o prompt. Não contém nada que o próprio interpretador leia. A ativação é apenas uma conveniência para uma pessoa que escreve python num prompt.
O que seleciona efetivamente o ambiente é o ficheiro de interpretador que executa. Quando /srv/myapp/.venv/bin/python arranca, o módulo Python site procura um ficheiro pyvenv.cfg no diretório que contém o executável e no diretório imediatamente acima. Encontrar /srv/myapp/.venv/pyvenv.cfg define sys.prefix como o venv, o que coloca o site-packages desse venv em sys.path. Esse é todo o mecanismo. Não precisa de uma variável de ambiente nem de uma shell.
Por isso, esta unidade nunca arranca:
[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 não é uma linha de comando de shell. O systemd executa diretamente um programa, portanto não existe nenhum builtin source, && é passado como um argumento literal e nenhuma expansão de shell ocorre além das poucas que o systemd documenta.
E esta unidade arranca e termina logo a seguir:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 é o interpretador do sistema e o seu sys.path nunca incluiu o seu venv. O mesmo comando funciona na sua sessão SSH apenas porque ativou o venv nessa sessão. Assim, a shell resolveu python3 através de PATH para .venv/bin/python3.
Envolver o comando em /bin/bash -c 'source ... && gunicorn ...' funciona. Também coloca uma shell entre o systemd e o processo sem qualquer benefício. Um caminho absoluto resolve o problema:
[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 deve apresentar active (running) com um Main PID que corresponda ao seu processo gunicorn. Se apresentar outra coisa, consulte o journal.
A linha Environment=PATH= não está presente por causa de ExecStart, que já contém um caminho completo. Ela existe por causa dos processos que a sua aplicação inicia. Um serviço recebe do systemd um PATH curto por predefinição. Por isso, código Python que chame subprocess.run(["ffmpeg", ...]), ou um comando de gestão que execute um console script do venv, não encontra o que precisa. Colocar o diretório bin do venv no início é a única parte de activate que um serviço usa efetivamente. Verifique o que a unidade recebeu com systemctl show -p Environment myapp.
A mesma regra aplica-se às tarefas agendadas. No Ubuntu, o cron não passa a uma tarefa o PATH da sua shell nem o do daemon. A menos que o crontab defina o próprio PATH, todas as tarefas recebem o /usr/bin:/bin compilado por predefinição, e /etc/environment não o substitui. Esse valor nunca contém o seu venv. Por isso, uma linha do crontab com python3 /srv/myapp/cleanup.py executa o interpretador do sistema e falha com ModuleNotFoundError às três da manhã. O cron envia o erro por correio ao proprietário do crontab, ou para o endereço MAILTO se definir um. Na maioria dos servidores, isso significa uma caixa de correio local que ninguém lê. Sem um programa de correio instalado, o cron descarta a saída e escreve apenas No MTA installed, discarding output no log do sistema. Escreva também o caminho absoluto do venv nessa linha. Para obter essa saída no journal e manter um registo da última execução, um par de serviço e temporizador do systemd usa a mesma linha ExecStart.
O Docker substitui esta decisão?
Um contentor tem o seu próprio sistema de ficheiros, por isso a questão muda de forma em vez de desaparecer. Numa imagem oficial como python:3.12-slim, o Python está incorporado em /usr/local e não contém nenhum marcador EXTERNALLY-MANAGED, por isso pip install como root é a forma prevista de adicionar pacotes, e um venv acrescenta pouco. Em vez disso, crie FROM ubuntu:24.04 e encontrará novamente externally-managed-environment dentro da imagem, pelo mesmo motivo que no host: é o interpretador da distribuição que contém o ficheiro marcador da distribuição.
Muitas imagens continuam a usar um venv, porque isso simplifica uma compilação em várias etapas. A etapa de compilação instala em /opt/venv, e a etapa de runtime copia esse diretório e deixa os compiladores para trás. O problema da ativação também é transportado. Uma linha RUN source /opt/venv/bin/activate afeta apenas a shell dessa camada de compilação, por isso, em runtime, o contentor inicia com o interpretador do sistema e gera ModuleNotFoundError. Defina ENV PATH="/opt/venv/bin:$PATH" ou forneça a CMD o caminho absoluto /opt/venv/bin/gunicorn. É o mesmo erro que ocorre com o systemd, mas noutro ficheiro.
Assim, um contentor substitui a questão do interpretador, porque a imagem fixa o interpretador e tudo o que está abaixo dele. Não substitui a questão da fixação de versões. Uma imagem criada a partir de um requirements.txt sem versão fixada resolve versões diferentes no próximo mês. Isso significa que a tag da imagem é reproduzível, mas a compilação que a produziu não é. Um ficheiro de bloqueio como uv.lock, ou um ficheiro de requisitos com todas as versões fixadas, elimina essa diferença, com ou sem contentor. E quando uma aplicação é executada num VPS sob systemd, um contentor limita-se sobretudo a transferir esta mesma decisão para um Dockerfile, uma vez que o systemd já reinicia um processo que falhou e captura o respetivo output no journal. Executar Docker num VPS é útil quando pretende que a própria imagem criada seja o artefacto que implementa.
FAQ
Posso simplesmente usar pip install com --break-system-packages?
Não num servidor que tem de continuar operacional. A flag faz exatamente o que indica: remove a proteção, e o pip escreve em /usr/local/lib/python3.12/dist-packages, que aparece antes do diretório do apt em sys.path. A sua versão passa então a ter precedência sobre a versão da distribuição em todos os scripts do sistema executados com /usr/bin/python3. O apt continua a considerar instalada a sua própria versão. Assim, nada deteta o conflito até algo deixar de funcionar. Numa imagem de container que reconstrói de raiz a cada vez, o problema fica limitado a essa imagem, pelo que essa utilização é justificável. Numa máquina que mantém, crie um venv. É um único comando.
Onde deve ficar o ambiente virtual num servidor?
Dentro do diretório da própria aplicação, em /srv/myapp/.venv, pertencente a um utilizador de deploy, com a conta de serviço a ter apenas permissões de leitura e execução. Mantenha um venv por aplicação. Um venv partilhado significa que uma atualização da primeira aplicação pode fazer a segunda deixar de funcionar. Não mova nem copie um venv depois de o criar. Cada script de entry point no diretório bin/ contém esse caminho absoluto na sua linha shebang. Por isso, um venv movido falha com bad interpreter: No such file or directory. Apague-o e reconstrua-o a partir de requirements.txt.
Porque é que o meu serviço systemd falha com ModuleNotFoundError?
Porque a unidade está a executar um interpretador que não é o do venv. Execute systemctl cat myapp e leia ExecStart. Este deve indicar /srv/myapp/.venv/bin/python ou um script de consola do mesmo diretório bin/, usando um caminho absoluto. Fazer source diretamente de activate em ExecStart não funciona, porque ExecStart não é uma shell, e o systemd comunica Failed to locate executable source com status=203/EXEC. Adicione Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin para que qualquer subprocesso iniciado pelo seu código também encontre as ferramentas do venv.
Devo usar uv em vez de venv e pip?
Use uv quando quiser um lockfile, quando o tempo de instalação for suficientemente lento para ser um problema ou quando precisar de uma versão do Python que a sua distribuição não disponibiliza. O uv cria um venv normal, pelo que a unidade do systemd e a disposição dos ficheiros não mudam, e uv sync --frozen instala exatamente o que o lockfile regista. Se uma única aplicação for instalada a partir de git com um requirements.txt fixo e a instalação terminar em segundos, python3 -m venv já é suficiente. Também terá menos um binário para manter atualizado no servidor.