Ambientes virtuais: venv e virtualenv

1. Introdução aos ambientes virtuais em Python

Todo desenvolvedor Python já enfrentou o problema: você instala um pacote globalmente com pip install, e semanas depois outro projeto precisa de uma versão diferente do mesmo pacote. Conflitos de dependências começam a surgir, e o gerenciamento se torna um pesadelo. Esse é o problema da poluição global de pacotes.

Um ambiente virtual resolve isso criando um diretório isolado que contém uma instalação independente do Python, com seu próprio interpretador, bibliotecas e scripts. Cada projeto pode ter seu próprio ambiente, com suas versões específicas de pacotes, sem interferir nos demais.

Atualmente, as duas principais ferramentas para criar ambientes virtuais são o venv (módulo nativo do Python a partir da versão 3.3) e o virtualenv (pacote de terceiros, mais antigo e com funcionalidades extras). Ambas cumprem o mesmo propósito básico, mas com diferenças importantes que exploraremos a seguir.

2. Trabalhando com venv (módulo padrão)

O venv é a ferramenta recomendada para projetos Python modernos (3.3+). Para criar um ambiente, use:

python -m venv meu_ambiente

Isso gera uma estrutura de diretórios como esta:

meu_ambiente/
├── bin/          # Scripts de ativação (Linux/macOS)
│   ├── activate
│   ├── python
│   └── pip
├── lib/
│   └── python3.x/
│       └── site-packages/  # Pacotes instalados aqui
├── include/
└── pyvenv.cfg    # Arquivo de configuração do ambiente

No Windows, os scripts ficam na pasta Scripts em vez de bin.

Para ativar o ambiente:

  • Linux/macOS: source meu_ambiente/bin/activate
  • Windows (CMD): meu_ambiente\Scripts\activate
  • Windows (PowerShell): meu_ambiente\Scripts\Activate.ps1

Após a ativação, o prompt do terminal muda para algo como (meu_ambiente) $, indicando que você está dentro do ambiente. Para desativar, basta digitar deactivate.

3. Gerenciamento de dependências dentro do ambiente

Com o ambiente ativado, instale pacotes normalmente com pip:

pip install requests pandas numpy

Para congelar as dependências instaladas em um arquivo:

pip freeze > requirements.txt

O arquivo requirements.txt gerado terá o formato:

numpy==1.24.3
pandas==2.0.3
python-dateutil==2.8.2
requests==2.31.0

Para recriar o mesmo ambiente em outra máquina:

pip install -r requirements.txt

Boas práticas: sempre versionar o requirements.txt no Git, mas adicionar a pasta do ambiente ao .gitignore:

meu_ambiente/
env/
venv/
.env/

4. virtualenv: alternativa avançada

O virtualenv é o predecessor do venv e ainda é amplamente utilizado, especialmente em projetos legados ou que exigem Python 2.

Instalação:

pip install virtualenv

Criação de ambiente:

virtualenv meu_ambiente

Opções úteis incluem:

virtualenv --python=python3.10 meu_ambiente  # Especifica versão do Python
virtualenv --system-site-packages meu_ambiente  # Permite acesso a pacotes do sistema
virtualenv --no-site-packages meu_ambiente  # Ambiente totalmente limpo (padrão)

Diferenças principais entre venv e virtualenv:

Característica venv virtualenv
Nativo do Python Sim (3.3+) Não (pacote externo)
Suporte a Python 2 Não Sim
Velocidade de criação Rápido Mais rápido (usa symlinks)
Ambientes limpos Sim Sim (com --no-site-packages)
Opções avançadas Limitadas Muitas (--python, --system-site-packages, etc.)

Opte pelo virtualenv quando precisar de suporte a Python 2, ou quando precisar de controle mais fino sobre a criação do ambiente. Para projetos novos com Python 3, o venv é suficiente e recomendado.

5. Gerenciamento de múltiplas versões do Python

Às vezes você precisa testar um projeto em diferentes versões do Python. Com o venv:

python3.10 -m venv env_py310
python3.11 -m venv env_py311

Com o virtualenv, você pode especificar o caminho completo do interpretador:

virtualenv --python=/usr/bin/python3.9 env_py39
virtualenv --python=/usr/local/bin/python3.11 env_py311

Para verificar a versão do Python dentro do ambiente ativado:

python --version
# Python 3.11.4

Isso é útil para projetos legados que ainda rodam em Python 2.7, ou para testar compatibilidade com versões mais recentes.

6. Integração com ferramentas de desenvolvimento

VS Code: ao abrir uma pasta com ambiente virtual, o VS Code detecta automaticamente o interpretador. Você pode selecioná-lo manualmente com Ctrl+Shift+P → Python: Select Interpreter.

PyCharm: cria automaticamente um ambiente virtual ao iniciar um novo projeto, ou permite selecionar um existente.

Ativação automática: ferramentas como direnv ou autoenv ativam o ambiente automaticamente ao entrar no diretório do projeto. Basta criar um arquivo .envrc (direnv) ou .env (autoenv) com:

source meu_ambiente/bin/activate

Integração com Poetry: o Poetry gerencia dependências e ambientes virtuais de forma mais robusta. Ele pode ser configurado para usar o venv internamente:

poetry config virtualenvs.in-project true

CI/CD: em pipelines, é comum criar ambientes temporários e usar caching de dependências:

# Exemplo para GitHub Actions
- name: Cache pip
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}

7. Boas práticas e resolução de problemas comuns

Sempre ativar o ambiente antes de instalar dependências. Um erro comum é instalar pacotes globalmente por engano.

Nunca versionar a pasta do ambiente. Adicione env/, venv/, .venv/ ao .gitignore.

Problemas frequentes:

  • PATH incorreto: após ativar o ambiente, which python deve apontar para dentro da pasta do ambiente. Se não, verifique se a ativação foi bem-sucedida.
  • Permissões negadas: no Linux, use chmod +x meu_ambiente/bin/activate se necessário.
  • Conflitos com pacotes do sistema: use --no-site-packages (virtualenv) ou crie o ambiente sem a flag --system-site-packages.

Limpeza de ambientes não utilizados:

rm -rf meu_ambiente  # Linux/macOS
rmdir /s meu_ambiente  # Windows (CMD)

Ambientes virtuais são descartáveis — se algo der errado, delete e recrie. Eles não devem conter dados importantes.

Referências