pip e venv: dependências isoladas por projeto

Por que um ambiente virtual

Se você instala tudo no mesmo Python, dois projetos que precisam de versões diferentes da mesma biblioteca se atropelam. Um ambiente virtual é uma pasta com um interpretador e um conjunto próprio de pacotes. Instalar ali não afeta nada fora dela.

Criar e ativar

Crie o ambiente dentro da pasta do projeto, com o nome .venv, que é a convenção que as ferramentas e os editores reconhecem sozinhos:

python3 -m venv .venv
source .venv/bin/activate
python --version

Windows e a política de execução do PowerShell

Se o PowerShell recusar o script de ativação, libere scripts assinados localmente, só para o seu usuário: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned. Feche e abra o terminal depois.

Como saber se você está dentro de um venv

O prompt do terminal ganha o prefixo (.venv). Dentro do Python, dá para checar comparando dois caminhos:

import sys

dentro_de_venv = sys.prefix != sys.base_prefix
print("Dentro de um venv:", dentro_de_venv)

Dentro de um venv: True

Dentro do ambiente virtual a saída é True. Fora dele, imprime False.

O pip

O pip instala pacotes do PyPI. Eu sempre uso python -m pip em vez de pip puro, porque assim o pip é obrigatoriamente o do interpretador ativo:

python -m pip install requests
python -m pip install "requests>=2.32,<3"
python -m pip list
python -m pip show requests
python -m pip uninstall requests

Para registrar as dependências e reinstalá-las em outra máquina:

python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

Especificadores de versão

O problema do pip freeze

O pip freeze lista tudo o que está instalado, dependências diretas e indiretas misturadas, sem distinguir o que você pediu do que veio de carona. Para reprodutibilidade de verdade, eu prefiro um arquivo de bloqueio (lockfile) gerado por Poetry ou uv, que você verá nos próximos capítulos.

A pasta .venv nunca vai para o Git. Coloque .venv/ no .gitignore. Quem clona o projeto recria o ambiente a partir da lista de dependências.