Existe uma frase que aparece em praticamente todo projeto Python que chega ao servidor: “na minha máquina funciona”.

Ela não é desculpa — é um diagnóstico. Na maior parte das vezes, significa que o ambiente do servidor não é o mesmo ambiente onde a aplicação foi construída: versão diferente da linguagem, bibliotecas em versões diferentes, ou dependências do sistema que existem em um lugar e não no outro.

Este guia trata de como eliminar essa diferença e de como conviver com a evolução das versões ao longo do tempo.

Por que o isolamento existe

Um servidor pode precisar rodar mais de uma aplicação Python — e elas podem exigir versões diferentes da mesma biblioteca.

Sem isolamento, isso é um conflito insolúvel: instalar a versão que uma aplicação precisa quebra a outra. E há um agravante: o próprio sistema operacional usa Python para ferramentas internas, então instalar bibliotecas no ambiente geral pode afetar o funcionamento do servidor.

A solução é criar ambientes isolados, um por aplicação, cada um com as próprias bibliotecas nas próprias versões. Cada aplicação enxerga apenas o que foi instalado no ambiente dela.

Três consequências práticas:

• Nunca instale bibliotecas no ambiente do sistema — o risco é afetar o próprio servidor.
• Cada aplicação tem o próprio ambiente, criado no momento da publicação.
• O ambiente é descartável: se algo der errado, recriá-lo do zero costuma ser mais rápido que investigar.

O terceiro ponto muda a forma de trabalhar: ambientes isolados não são consertados, são recriados. Isso só funciona se as dependências estiverem declaradas de forma completa.

Reproduzir o mesmo ambiente

A parte que elimina o “funciona na minha máquina”.

Declarar apenas os nomes das bibliotecas não basta — elas evoluem, e uma instalação feita hoje pode trazer versões diferentes da instalação de três meses atrás.

O que garante reprodutibilidade:

1. Fixar as versões exatas de cada dependência, e não apenas os nomes.
2. Incluir as dependências das dependências, que também evoluem e podem quebrar.
3. Versionar esse registro junto com o código.
4. Instalar sempre a partir dele, em qualquer ambiente.
5. Separar dependências de desenvolvimento das de produção, para não instalar ferramentas de teste no servidor.

O item 2 é a causa mais frequente de comportamento divergente: você fixou a versão da biblioteca que usa, mas ela depende de outras que não foram fixadas — e uma delas mudou entre a sua instalação e a do servidor.

E o item 5 tem efeito de segurança além de tamanho: ferramentas de desenvolvimento em produção ampliam a superfície de exposição sem entregar nada.

O que não vem junto

Um ponto que confunde: nem tudo o que a aplicação precisa está nas dependências declaradas.

Algumas bibliotecas dependem de componentes do sistema operacional — bibliotecas de compressão, de processamento de imagem, de banco de dados, de criptografia. Elas precisam existir no servidor antes, e não são instaladas pelo gerenciador de dependências da linguagem.

O sintoma é característico: a instalação falha com um erro que menciona algo que não está no seu código, ou a aplicação sobe e falha ao usar uma funcionalidade específica.

O que ajuda:

• Documentar os requisitos de sistema junto com as dependências da aplicação.
• Usar o mesmo sistema operacional em desenvolvimento e produção, quando possível.
• Testar a instalação do zero periodicamente, em um ambiente limpo — é o que revela dependências não documentadas.

O último item é o mais revelador: uma instalação que só funciona em uma máquina onde tudo já existe esconde exatamente o que falta documentar.

A versão da linguagem

A decisão que precede todas as outras.

O Python segue um ciclo de vida publicado: cada versão tem um período de suporte definido, com correções de segurança até uma data conhecida. Isso significa que a versão em uso hoje tem prazo — e ele é consultável.

O que considerar ao escolher:

• Não use a versão mais recente imediatamente. Bibliotecas levam um tempo para oferecer suporte, e usar a mais nova pode significar não conseguir instalar o que você precisa.
• Não use a mais antiga ainda suportada sem motivo, porque o prazo de atualização já estará próximo.
• Verifique o que as suas dependências principais suportam antes de decidir.
• Fixe a versão no ambiente, em vez de depender do que estiver instalado no sistema.

O primeiro item é contraintuitivo para quem gosta de estar atualizado: a versão mais recente é, temporariamente, a que tem menos suporte do ecossistema. Esperar alguns meses costuma ser a escolha mais produtiva.

O método de planejamento do ciclo de atualizações está no artigo sobre planejar atualizações de versão, e vale integralmente aqui.

Atualizar a versão da linguagem

O procedimento, com as particularidades do Python:

1. Verifique a compatibilidade das dependências antes de qualquer coisa. É aqui que a maior parte dos bloqueios aparece.
2. Crie um ambiente novo com a versão de destino, em vez de tentar migrar o existente.
3. Instale as dependências a partir do registro versionado.
4. Resolva as incompatibilidades que aparecerem, uma a uma.
5. Execute os testes, se houver, e percorra os caminhos reais da aplicação.
6. Compare o comportamento com o ambiente anterior, especialmente em rotinas de dados.
7. Publique com caminho de volta disponível.

O passo 2 aproveita a natureza descartável dos ambientes isolados: criar um novo é mais limpo e mais rápido que converter o antigo, e permite manter os dois lado a lado durante a validação.

E o passo 6 merece atenção em aplicações de processamento: mudanças sutis de comportamento em bibliotecas de cálculo podem alterar resultados sem gerar erro nenhum. Comparar saídas entre as versões é a única forma de detectar isso.

Mais de uma aplicação no mesmo servidor

Um cenário comum e perfeitamente viável, com alguns cuidados:

• Um ambiente isolado por aplicação, sem exceção.
• Versões da linguagem podem ser diferentes entre elas, se necessário.
• Cada aplicação com o próprio usuário do sistema, o que contém o alcance de um comprometimento.
• Portas internas distintas, com o proxy reverso encaminhando conforme o endereço — o componente está no artigo sobre o que é um proxy reverso.
• Supervisão separada, para que cada uma reinicie de forma independente.
• Recursos considerados no conjunto, porque todas dividem a mesma memória — o método está no artigo sobre dimensionar um servidor para aplicações Python.

O terceiro item é uma medida de contenção simples e frequentemente ignorada: se as aplicações rodam sob o mesmo usuário, um comprometimento em uma alcança os arquivos da outra.

O que verificar no ambiente do servidor

Antes de publicar, uma checagem que evita surpresas:

Item	Por que importa
Versão da linguagem disponível	Pode ser diferente da esperada
Ferramenta de ambientes isolados	Precisa estar instalada
Bibliotecas do sistema	Algumas dependências exigem
Compilador disponível	Certas bibliotecas compilam na instalação
Acesso à internet do servidor	Para baixar dependências
Permissão para processos permanentes	Exigência da aplicação

O quarto item surpreende quem nunca esbarrou nele: algumas bibliotecas são compiladas durante a instalação, e sem as ferramentas de compilação disponíveis a instalação falha com um erro que não menciona isso claramente.

A alternativa, quando o servidor não pode ter compilador, é instalar em outro lugar e enviar o resultado pronto — o mesmo raciocínio aplicado à publicação de aplicações PHP.

Conclusão

“Na minha máquina funciona” quase sempre significa que o ambiente do servidor não é o mesmo onde a aplicação foi construída. A solução tem duas partes: isolar e reproduzir.

Isolar significa um ambiente por aplicação, nunca no ambiente do sistema — que o próprio servidor usa. Reproduzir significa fixar as versões exatas, incluindo as dependências das dependências, que é onde a divergência mais aparece.

E uma escolha que contraria a intuição: a versão mais recente da linguagem é, temporariamente, a que tem menos suporte do ecossistema. Verificar o que as suas dependências principais suportam, antes de decidir, evita descobrir isso na hora da instalação. Conheça o Cloud Server para Python da TBF Host e avalie o ambiente adequado à sua aplicação.

Perguntas frequentes

Por que minha aplicação Python funciona local e falha no servidor?

Quase sempre porque os ambientes são diferentes: versão da linguagem, versões das bibliotecas ou dependências do sistema operacional que existem em um lugar e não no outro. A solução é isolar o ambiente e fixar as versões exatas de todas as dependências.

Por que não instalar bibliotecas Python direto no sistema?

Porque o próprio sistema operacional usa Python para ferramentas internas — instalar bibliotecas no ambiente geral pode afetar o funcionamento do servidor. Além disso, aplicações diferentes podem exigir versões diferentes da mesma biblioteca, o que sem isolamento é um conflito insolúvel.

Fixar as versões das bibliotecas é suficiente?

Não. É preciso incluir também as dependências das dependências, que evoluem por conta própria. É a causa mais frequente de comportamento divergente: você fixou o que usa diretamente, mas algo abaixo disso mudou entre a sua instalação e a do servidor.

Por que a instalação falha com erro sobre algo que não está no meu código?

Porque algumas bibliotecas dependem de componentes do sistema operacional — compressão, processamento de imagem, banco de dados, criptografia — que precisam existir no servidor antes e não são instalados pelo gerenciador de dependências da linguagem.

Devo usar a versão mais recente do Python?

Não imediatamente. Bibliotecas levam um tempo para oferecer suporte, e a versão mais nova é temporariamente a que tem menos suporte do ecossistema. Também não vale usar a mais antiga ainda suportada sem motivo, porque o prazo de atualização já estará próximo.

Como atualizar a versão do Python de uma aplicação?

Verificando primeiro a compatibilidade das dependências, criando um ambiente novo com a versão de destino em vez de converter o existente, instalando a partir do registro versionado, resolvendo incompatibilidades uma a uma e comparando o comportamento com o ambiente anterior.

Posso rodar várias aplicações Python no mesmo servidor?

Pode, com um ambiente isolado por aplicação — e, se necessário, versões diferentes da linguagem entre elas. Vale também dar a cada uma um usuário próprio do sistema, para conter o alcance de um eventual comprometimento, e considerar os recursos no conjunto.

Como descobrir dependências que não estão documentadas?

Testando a instalação do zero em um ambiente limpo, periodicamente. Uma instalação que só funciona em uma máquina onde tudo já existe esconde exatamente o que falta documentar — e o servidor novo é onde isso aparece, no pior momento.