Curso de Python / Criar ambientes virtuais e gerenciar pacotes com pip

Um ambiente virtual separa os pacotes Python de um projeto dos pacotes de outros projetos. Use python -m pip para executar pip com o interpretador escolhido e confira o caminho antes de instalar ou remover dependências.

Entenda o que o ambiente virtual separa

Dois projetos podem precisar de versões diferentes do mesmo pacote. Atualizar uma instalação compartilhada para atender a um deles pode afetar o outro. Criar uma pasta .venv por projeto permite manter espaços de instalação separados. Essa separação não é uma barreira de segurança: o código continua tendo as permissões do usuário e pode acessar arquivos fora do ambiente.

O guia oficial de instalação com pip e ambientes virtuais mostra como usar esses componentes em conjunto. No editor, também é necessário selecionar esse ambiente: a aula sobre execução de Python no VS Code apresenta as verificações de caminho.

Crie e ative o ambiente do projeto

Abra um terminal na pasta do projeto, usando Python 3.12 ou posterior. Se .venv já existir, identifique o ambiente e seus arquivos antes de tentar recriá-lo. Em um projeto novo, use o interpretador desejado para executar:

python -m venv .venv

No macOS ou Ubuntu, se o nome disponível fora de um ambiente for python3, use python3 -m venv .venv. No Windows PowerShell, ative o ambiente com:

.\.venv\Scripts\Activate.ps1

No macOS ou Ubuntu, em Bash ou Zsh, use:

source .venv/bin/activate

A ativação muda a procura de comandos na sessão atual do shell. Ela facilita usar python sem escrever o caminho completo, mas não é obrigatória. Se a política do PowerShell bloquear o script, siga a política da organização e use .venv\Scripts\python.exe diretamente. Não é necessário reduzir a política de execução de todo o computador. Nos sistemas Unix, o executável equivalente fica em .venv/bin/python.

Os comandos da próxima seção pressupõem que python já seleciona o ambiente. Verifique o caminho antes de prosseguir; se preferir a chamada explícita, substitua o primeiro python de cada comando pelo caminho do executável do ambiente.

Instale um pacote e registre as dependências

Este exemplo usa pandas, uma biblioteca de dados tabulares cuja documentação de instalação identifica as distribuições oficiais. O procedimento precisa de acesso à rede e a uma fonte de pacotes permitida no seu ambiente. Instale somente o necessário e confira o nome do pacote; o nome usado na instalação nem sempre coincide com o nome usado em import.

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

A primeira linha instala pandas e as dependências necessárias. A segunda mostra informações como Name, Version e Location; a localização deve ficar no ambiente do projeto. A terceira grava os pacotes instalados em requirements.txt, na pasta atual. Se esse arquivo já existir, o redirecionamento > substitui seu conteúdo: preserve a versão anterior antes de gerar outra.

A quarta linha lê o arquivo e instala os requisitos. No mesmo ambiente, ela pode informar que as versões já estão presentes. Para testar a reconstrução, crie outro ambiente em uma pasta separada e execute a instalação usando o Python desse novo ambiente com o mesmo arquivo de requisitos. Confira novamente a localização de pip e não apague o ambiente anterior antes de verificar o novo.

Conforme a referência de pip freeze, essa saída descreve os pacotes instalados; ela não é um arquivo de travamento calculado por um resolvedor. Também não garante que as mesmas versões sejam instaláveis em todo sistema operacional ou versão de Python e não inclui, por si só, hashes para verificar os arquivos baixados.

A codificação produzida pelo redirecionamento pode variar com a versão do PowerShell. Se pip não conseguir ler o arquivo, confira a codificação no editor e salve-o como texto UTF-8. Não altere nomes ou versões apenas para ocultar um erro de leitura. Depois de ativar ou trocar um ambiente, use estas verificações para confirmar a seleção:

python -c "import sys; print(sys.executable)"
python -m pip --version

sys.executable e o caminho informado por pip devem apontar para a mesma .venv. O número exato da versão de cada ferramenta varia; a pasta de destino é o que identifica onde o pacote será instalado.

Diagnostique o ambiente antes de reinstalar

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip check

pip check verifica se os pacotes instalados têm dependências compatíveis. Quando não encontra problemas, a mensagem esperada é No broken requirements found.. Ele não substitui os testes do programa nem garante que toda combinação de pacotes funcione corretamente. A referência de pip check mostra também as mensagens para requisitos ausentes ou incompatíveis.

• ModuleNotFoundError: identifique primeiro o interpretador que executa o arquivo. Instalar globalmente como administrador não corrige um programa que usa outro ambiente.
• Falha de certificado ou de proxy: confira a rede e a configuração de confiança da instalação. Desativar a verificação TLS não corrige a causa.
• Ausência de uma distribuição compatível: confira a versão de Python, o sistema operacional e os requisitos do pacote antes de mudar de versão ou de método de instalação.

Use deactivate ao terminar uma sessão ativada. Para remover um pacote deste ambiente, execute python -m pip uninstall nome-do-pacote com o Python correto e confira o que será removido. Antes de recriar .venv, preserve o código e requirements.txt fora dessa pasta; reconstruir o ambiente e apagar os dados do projeto são operações diferentes.