requirements.txt: a receita do projeto

Congelar as dependências

Você já sabe listar os pacotes com pip list. Agora vem o passo que transforma essa lista numa receita guardável. O comando pip freeze mostra os pacotes instalados num formato pronto para reinstalar, com a versão fixada em cada um. Sozinho, ele só imprime na tela. A mágica é redirecionar essa saída para um arquivo com o sinal de maior, criando o requirements.txt. A partir daí, esse arquivo carrega a lista exata do que o projeto usa.

# com o ambiente ativo, gere a receita do projeto
pip freeze > requirements.txt

pip freeze imprime as versões; o > grava tudo no arquivo requirements.txt.

Abra o requirements.txt em qualquer editor e você verá algo direto: uma linha por pacote, no formato nome==versão. O sinal de igual duplo trava a versão exata. Não é uma faixa aproximada; é aquela versão específica que funcionou no seu projeto. Essa precisão é justamente o valor do arquivo. Ele não diz apenas quais bibliotecas o projeto usa, e sim quais versões, para que o comportamento seja o mesmo em qualquer lugar que a receita for aplicada.

certifi==2024.x
charset-normalizer==3.x
idna==3.x
requests==2.x
urllib3==2.x

Conteúdo típico do requirements.txt: cada pacote com a versão travada.

Recriar o ambiente a partir da receita

A receita só brilha quando você a aplica. Imagine que você trocou de computador, ou baixou o projeto de um repositório, ou apagou a pasta .venv para começar limpo. Você recria o ambiente do zero com um único comando: pip install -r requirements.txt. O -r quer dizer requirements, ou seja, instale tudo que está listado neste arquivo. O pip lê o requirements.txt linha por linha e instala cada pacote na versão exata indicada, montando a despensa idêntica à original.

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Do zero: crie o ambiente, ative e instale tudo da receita de uma vez.

Esse é o momento em que o esforço de manter a receita se paga. Sem ela, quem pega o seu projeto precisa adivinhar quais pacotes instalar e em quais versões, e é comum surgir aquele bug que só acontece na máquina de uma pessoa, por causa de uma versão diferente. Com o requirements.txt versionado junto do código, qualquer um monta o ambiente exato em segundos. É o que quer dizer projeto reprodutível: mesma receita, mesmo resultado, em qualquer lugar.

O que versionar e o que deixar de fora

Fica clara agora a divisão de trabalho entre a pasta e o arquivo. A pasta .venv é pesada, específica do seu sistema operacional e recriável a qualquer instante; ela não entra no controle de versão, e o nome vai para o .gitignore. O requirements.txt, ao contrário, é leve, portátil e essencial; ele entra no repositório junto do código. Em uma frase: versione a receita, não a despensa. Quem clona o projeto recria a despensa a partir da receita, e não precisa carregar a sua.

Um cuidado prático: sempre gere o requirements.txt com o ambiente virtual ativo. Se você rodar o pip freeze fora do ambiente, ele lista os pacotes globais, e a receita fica errada, cheia de coisas que o projeto nem usa. Com o (.venv) ligado, o freeze enxerga só a despensa daquele projeto, e a lista sai enxuta e fiel. Esse é o fluxo profissional completo: criar o ambiente, ativar, instalar o que precisa, congelar a receita e versioná-la junto do código.