Skip to main content
O arquivo requirements.txt é o padrão da indústria para especificar e gerenciar dependências em projetos Python. Este guia mostra como criar, configurar e usar o requirements.txt para garantir consistência entre ambientes de desenvolvimento e produção.

​
O que é um arquivo requirements.txt?

Um arquivo requirements.txt lista todos os pacotes Python externos que seu projeto necessita, com suas versões específicas. Isso permite que:
  • Você e sua equipe mantenham ambientes idênticos
  • Novos colaboradores reproduzam o ambiente exatamente
  • O deploy na Square Cloud funcione com as dependências corretas
1

Crie e ative um ambiente virtual

Trabalhar dentro de um ambiente virtual é essencial para manter as dependências do seu projeto isoladas do sistema Python global. Isso evita conflitos de versão e garante reprodutibilidade.Crie o ambiente virtual na raiz do seu projeto (use python3 se o python não for encontrado no macOS/Linux):
Ative-o com um dos comandos abaixo, dependendo do seu sistema:Windows:
macOS/Linux:
Em seguida, instale os pacotes que o seu projeto usa, por exemplo:
2

Liste as dependências do projeto

Sempre especifique versões exatas com == para garantir reprodutibilidade e evitar quebras por atualizações incompatíveis em produção.

​
Opção A: Gerar com pip freeze (Recomendado)

Com o ambiente virtual ativado, grave no arquivo cada pacote instalado e sua versão exata:
Dentro de um ambiente virtual, o pip freeze lista apenas os pacotes instalados nele (as suas dependências e as sub-dependências delas), já fixados com ==.
Fora de um ambiente virtual, o pip freeze lista todos os pacotes instalados no seu sistema. Revise o arquivo e remova o que o seu projeto não usa.

​
Opção B: Criar manualmente

Crie um arquivo requirements.txt na raiz do seu projeto e liste os pacotes que o seu projeto usa, com suas versões:
requirements.txt
3

Revise e valide as dependências

Abra o arquivo requirements.txt em seu editor de texto e:
  1. Revise a lista de pacotes
  2. Remova dependências desnecessárias
  3. Atualize versões conforme necessário
  4. Certifique-se de estar usando versões exatas (com ==)
4

Instale as dependências

Para instalar todas as dependências listadas:
Este comando garante que todos os colaboradores e ambientes de produção usem exatamente as mesmas versões.
5

Versione e compartilhe

Com o requirements.txt pronto, você pode:
  • Compartilhá-lo com sua equipe
  • Colocá-lo no controle de versão (git)
  • Garantir que todos trabalhem com as mesmas versões
  • Simplificar o deploy na Square Cloud
Quando você hospeda seu projeto na Square Cloud, o arquivo requirements.txt é detectado automaticamente e as dependências dele são instaladas com pip install -r requirements.txt antes de a sua aplicação iniciar.

​
Boas práticas e dicas

  • Mantenha atualizado: Revise e atualize o requirements.txt regularmente conforme adiciona novas dependências
  • Use versões exatas: Sempre use == em vez de >, >= ou sem versão para evitar surpresas em produção
  • Revisar pip freeze: Se usar pip freeze, revise o arquivo antes de commitar, pois pode incluir pacotes auxiliares desnecessários
  • Versionamento: Commit o requirements.txt no git para rastrear mudanças de dependências
  • Ambiente isolado: Mantenha um ambiente virtual por projeto para evitar conflitos globais
  • Testar localmente: Antes de fazer deploy, teste o arquivo com pip install -r requirements.txt em um novo ambiente

​
Próximos passos

Com seu arquivo requirements.txt configurado:
  1. Faça commit dele no seu repositório Git.
  2. Hospede o seu projeto com o guia do runtime Python, ou siga um guia de framework: Django, Flask ou FastAPI.
  3. Faça deploy automático a partir do GitHub a cada push.