Python Brasil —...
Guia

Virtual Environments em Python: Guia Completo

Aprenda a criar e gerenciar ambientes virtuais em Python com venv. Isolamento de dependências, ativação, desativação e boas práticas

5 min de leitura

Introdução

Ambientes virtuais são uma das ferramentas mais importantes do ecossistema Python. Eles permitem isolar as dependências de cada projeto, evitando conflitos entre bibliotecas e garantindo que cada aplicação tenha exatamente as versões necessárias.

Sem ambientes virtuais, todas as bibliotecas são instaladas globalmente, o que causa problemas quando dois projetos precisam de versões diferentes da mesma biblioteca. Neste guia, vamos entender por que ambientes virtuais são essenciais e como usá-los no dia a dia.

Por que usar ambientes virtuais?

Imagine que você tem dois projetos:

  • Projeto A precisa de Django 4.2
  • Projeto B precisa de Django 5.0

Sem ambientes virtuais, ambos compartilham o mesmo Python do sistema. Ao instalar Django 5.0 para o Projeto B, você quebra o Projeto A. Ambientes virtuais resolvem isso criando instalações Python independentes para cada projeto.

Outros benefícios incluem:

  • Reprodutibilidade: o arquivo requirements.txt registra exatamente as versões usadas
  • Limpeza: ao terminar um projeto, basta apagar a pasta do ambiente virtual
  • Segurança: evita modificar o Python do sistema operacional
  • Colaboração: colegas podem recriar o mesmo ambiente facilmente

Criando um ambiente virtual com venv

O módulo venv vem embutido no Python 3.3+ e é a forma padrão de criar ambientes virtuais:

# Crie uma pasta para o projeto
mkdir meu-projeto
cd meu-projeto

# Crie o ambiente virtual
python3 -m venv venv

O segundo venv é o nome da pasta que será criada. Você pode usar qualquer nome, mas venv e .venv são convenções amplamente adotadas.

A estrutura criada contém:

venv/
    bin/          # Scripts e executáveis (Linux/macOS)
    Scripts/      # Scripts e executáveis (Windows)
    lib/          # Bibliotecas instaladas
    include/      # Headers C (para extensões compiladas)
    pyvenv.cfg    # Configuração do ambiente

Ativando o ambiente virtual

Linux e macOS

source venv/bin/activate

Windows (PowerShell)

venv\Scripts\Activate.ps1

Windows (CMD)

venv\Scripts\activate.bat

Quando o ambiente está ativo, o prompt do terminal muda para mostrar o nome do ambiente:

(venv) usuario@maquina:~/meu-projeto$

Verifique que o Python do ambiente está sendo usado:

which python    # Linux/macOS
where python    # Windows

O resultado deve apontar para o Python dentro da pasta venv/.

Instalando bibliotecas

Com o ambiente ativo, use pip normalmente. As bibliotecas são instaladas apenas dentro do ambiente virtual:

pip install flask
pip install requests
pip install pandas numpy matplotlib

Para verificar as bibliotecas instaladas:

pip list

Gerando o requirements.txt

O requirements.txt registra todas as dependências do projeto e suas versões:

pip freeze > requirements.txt

O arquivo gerado terá conteúdo semelhante a:

flask==3.1.0
requests==2.32.0
pandas==2.2.0
numpy==1.26.0
matplotlib==3.9.0

Recriando o ambiente em outra máquina

Quando um colega ou servidor precisa instalar o projeto:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Isso instala exatamente as mesmas versões que você usou, garantindo que o código funcione de forma idêntica.

Desativando o ambiente

Para sair do ambiente virtual e voltar ao Python do sistema:

deactivate

O prompt volta ao normal, sem o prefixo (venv).

Removendo um ambiente virtual

Como o ambiente virtual é apenas uma pasta, basta apagar:

rm -rf venv      # Linux/macOS
rmdir /s venv    # Windows

Isso não afeta o código do projeto, apenas remove as bibliotecas instaladas.

Configurando o .gitignore

Nunca faça commit da pasta do ambiente virtual no Git. Adicione ao .gitignore:

venv/
.venv/

O requirements.txt sim deve ser commitado, pois ele permite que outros recriem o ambiente.

Ambientes virtuais com versões específicas do Python

Se você tem múltiplas versões do Python instaladas, pode criar o ambiente com uma versão específica:

python3.11 -m venv venv
python3.12 -m venv venv

Para verificar a versão usada:

python --version

Usando venv no VS Code

O VS Code detecta automaticamente ambientes virtuais na pasta do projeto. Se não detectar:

  1. Pressione Ctrl + Shift + P (ou Cmd + Shift + P no macOS)
  2. Digite “Python: Select Interpreter”
  3. Selecione o interpretador dentro de venv/bin/python

O terminal integrado do VS Code ativa o ambiente automaticamente ao abrir.

Usando venv no PyCharm

O PyCharm oferece criação de ambientes virtuais pela interface:

  1. Vá em File > Settings > Project > Python Interpreter
  2. Clique no ícone de engrenagem e selecione Add
  3. Escolha Virtualenv Environment > New environment

O PyCharm ativa o ambiente automaticamente em todos os terminais e configurações de execução.

Alternativas ao venv

Embora o venv seja suficiente para a maioria dos casos, existem alternativas:

  • virtualenv: versão mais antiga e com mais recursos que o venv. Funciona com Python 2 também.
  • conda: gerenciador de ambientes e pacotes, popular em ciência de dados. Gerencia tanto pacotes Python quanto bibliotecas do sistema.
  • Poetry: gerenciador de dependências moderno que cria ambientes virtuais automaticamente.
  • Pipenv: combina pip e virtualenv com um arquivo Pipfile para gerenciar dependências.

Problemas comuns

“python3: comando não encontrado”

No Windows, tente python em vez de python3. No Linux, pode ser necessário instalar:

sudo apt install python3-venv

Ambiente não ativa no PowerShell

O Windows pode bloquear scripts por padrão. Execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Bibliotecas não encontradas após ativar

Verifique se ativou o ambiente correto e se está na pasta certa do projeto. Use pip list para verificar o que está instalado.

Boas práticas

  • Sempre crie um ambiente virtual para cada projeto
  • Use nomes padronizados: venv ou .venv
  • Gere o requirements.txt regularmente com pip freeze
  • Mantenha o .gitignore atualizado
  • Documente a versão do Python necessária no README do projeto
  • Considere usar pip install --upgrade pip ao criar um novo ambiente

Conclusão

Ambientes virtuais são uma prática essencial no desenvolvimento Python. Eles previnem conflitos de dependências, facilitam a colaboração e tornam projetos reprodutíveis. O módulo venv, incluso no Python padrão, é tudo que você precisa para começar. Adote o hábito de criar um ambiente virtual para cada projeto e você evitará muitas dores de cabeça no futuro.

Todos os Guias