O Ubuntu 24.04 inclui o Python 3.12, mas instalar pacotes com um simples pip falha agora com o erro «externally-managed-environment». A solução é isolar cada projeto num ambiente virtual. Este guia mostra como preparar o seu VPS Linux Infrawire, gerir as dependências corretamente e manter uma aplicação ativa como serviço systemd.
📋 Pré-requisitos
- Um VPS com Ubuntu 24.04 ou Debian 12 e acesso SSH como root (o IP e a palavra-passe root estão na sua área de cliente)
- Um projeto Python ou um script simples para testar
- Noções básicas de linha de comandos
1. Instalar o Python 3, o pip e o venv
O Python 3 costuma vir pré-instalado, mas o pip e o módulo venv são pacotes separados.
Bashapt update apt install -y python3 python3-pip python3-venv python3-dev build-essential python3 --version pip3 --version
2. Perceber o erro PEP 668
Executar pip install requests como root no Ubuntu 24.04 ou Debian 12 mostra:
TEXTerror: externally-managed-environment
Esta proteção (PEP 668) impede o pip de substituir ficheiros geridos pelo apt e de estragar ferramentas do sistema. Não a contorne com --break-system-packages. Use uma das três opções limpas abaixo.
3. Criar um ambiente virtual
Um ambiente virtual é uma cópia privada do Python e do pip para um único projeto.
Bashmkdir -p /opt/myapp && cd /opt/myapp python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install requests flask gunicorn
O prompt passa a começar por (venv). Saia do ambiente com deactivate.
4. Gerir dependências com requirements.txt
Fixe as versões exatas para poder reconstruir o projeto de forma idêntica noutro servidor.
Bashpip freeze > requirements.txt # Numa máquina nova python3 -m venv venv source venv/bin/activate pip install -r requirements.txt
5. Instalar ferramentas de linha de comandos com o pipx
Para ferramentas autónomas (httpie, yt-dlp, black...), o pipx dá a cada uma o seu próprio ambiente virtual oculto e expõe o comando globalmente.
Bashapt install -y pipx pipx ensurepath pipx install httpie
Abra depois uma nova sessão para carregar o PATH atualizado. Para uma biblioteca com pacote Debian, apt install python3-requests também é uma escolha válida.
6. Executar a aplicação como serviço systemd
Crie um utilizador dedicado sem privilégios e depois uma unidade que arranque o interpretador do ambiente virtual (aqui o Gunicorn a servir um objeto Flask chamado app em app.py).
Bashuseradd --system --home /opt/myapp --shell /usr/sbin/nologin myapp chown -R myapp:myapp /opt/myapp
Crie /etc/systemd/system/myapp.service:
INI1[Unit] 2Description=My Python application 3After=network.target 4 5[Service] 6User=myapp 7WorkingDirectory=/opt/myapp 8ExecStart=/opt/myapp/venv/bin/gunicorn --bind 127.0.0.1:8000 app:app 9Restart=on-failure 10RestartSec=5 11 12[Install] 13WantedBy=multi-user.target
Bashsystemctl daemon-reload systemctl enable --now myapp
Coloque um proxy inverso como o nginx à frente da porta 8000 para a expor na Internet.
✅ Verificar
Bashwhich python # deve apontar para dentro de /opt/myapp/venv quando ativado pip list systemctl status myapp --no-pager journalctl -u myapp -n 50 --no-pager curl -I http://127.0.0.1:8000
🔧 Resolução de problemas
The virtual environment was not created successfully because ensurepip is not available : falta o pacote venv. Instale-o com apt install python3-venv (ou python3.12-venv) e repita o comando.
status=203/EXEC no systemd : o caminho em ExecStart está errado ou o ficheiro não é executável pelo utilizador do serviço. Verifique com ls -l /opt/myapp/venv/bin/gunicorn e as permissões definidas antes.
ModuleNotFoundError apenas sob o systemd : o serviço usa o Python do sistema em vez do ambiente virtual. Chame sempre /opt/myapp/venv/bin/python ou o binário de venv/bin no ExecStart.
pip: command not found : use python3 -m pip ou ative primeiro o ambiente virtual.
🎉 Os seus projetos Python estão agora isolados, reprodutíveis e a correr como um serviço fiável!