Ambiente Virtual Python: Como Criar e Ativar o venv

Como criar um ambiente virtual Python

Para criar um ambiente virtual Python, entre na pasta do projeto e execute python -m venv .venv. Depois, ative o ambiente com source .venv/bin/activate no Linux ou macOS, .venv\Scripts\Activate.ps1 no PowerShell ou .venv\Scripts\activate.bat no Prompt de Comando. Para confirmar que funcionou, execute python -c "import sys; print(sys.executable)": o caminho deve apontar para dentro da pasta .venv. Desative com deactivate e remova o ambiente simplesmente apagando a pasta .venv.

Um ambiente virtual Python isola as dependências de cada projeto. Assim, uma aplicação pode usar Django 4.2 enquanto outra usa Django 5 sem que uma instalação substitua a outra. O isolamento também evita alterar o Python mantido pelo sistema operacional e facilita reproduzir o projeto em outra máquina.

Neste guia você aprenderá a criar, ativar, verificar, desativar e remover um ambiente com o módulo venv, que já acompanha o Python 3. Para comparar o venv com ferramentas que também gerenciam dependências, veja pip, uv, Poetry e Conda.

mkdir meu-projeto
cd meu-projeto
python -m venv .venv

Referência rápida: comandos do venv

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

O que faz o comando python -m venv .venv?

O módulo venv vem embutido no Python 3.3 ou mais recente. Neste comando, o primeiro venv é o nome do módulo executado e .venv é a pasta que será criada:

python -m venv .venv

No Linux, algumas distribuições usam o comando python3:

python3 -m venv .venv

Você pode chamar a pasta de venv, mas .venv é uma convenção útil: o ponto deixa o diretório oculto em sistemas Unix, e editores como VS Code e PyCharm reconhecem esse nome. A estrutura inclui:

.venv/
    bin/          # Executáveis no Linux e macOS
    Scripts/      # Executáveis no Windows
    lib/          # Bibliotecas instaladas
    include/      # Cabeçalhos para extensões compiladas
    pyvenv.cfg    # Configuração e Python de origem

Ativando o ambiente virtual

Linux e macOS

source .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\Activate.ps1

Windows (Prompt de Comando/CMD)

.venv\Scripts\activate.bat

Quando o ambiente está ativo, o prompt normalmente passa a mostrar seu nome:

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

A mudança no prompt ajuda, mas a verificação mais confiável é consultar o executável usado pelo próprio Python:

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

O resultado deve terminar em .venv/bin/python no Linux ou macOS, ou .venv\Scripts\python.exe no Windows. Você também pode verificar pelo sistema:

which python    # Linux/macOS
where python    # Windows

Se o caminho não estiver dentro de .venv, o ambiente não foi ativado nesse terminal.

Instalando bibliotecas

Com o ambiente ativo, instale bibliotecas usando python -m pip:

python -m pip install --upgrade pip
python -m pip install flask
python -m pip install requests
python -m pip install pandas numpy matplotlib

Esse formato executa o pip ligado exatamente ao interpretador retornado por python. Usar apenas pip install ... também pode funcionar, mas em máquinas com múltiplas versões do Python o comando pip pode apontar para outra instalação. python -m pip reduz esse erro.

Para conferir o vínculo e as bibliotecas instaladas:

python -m pip --version
python -m pip list

A primeira saída deve mostrar um caminho dentro de .venv.

Gerando o requirements.txt

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

python -m 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
python -m 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 /q .venv     # Windows CMD

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 python -m 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.

Outras linguagens resolvem o isolamento de dependências de formas diferentes. Em Go, os módulos são nativos e dispensam ambientes virtuais, enquanto Rust usa o Cargo para gerenciar dependências por projeto automaticamente.