Ambiente virtual em Python: por que usar e como criar

Antes de instalar qualquer biblioteca em um projeto Python, você precisa entender onde essa biblioteca vai parar. Sem ambiente virtual, tudo vai para o Python global do seu sistema — e isso cria um problema silencioso que vai te atrapalhar mais cedo ou mais tarde.

O problema que o ambiente virtual resolve

Imagine que você tem dois projetos no mesmo computador:

• Projeto A (legado): usa Django 3.2
• Projeto B (novo): usa Django 5.0

Se você instalar tudo no Python global, só uma versão do Django pode existir ao mesmo tempo. Atualizar para o Projeto B quebra o Projeto A. Sem saída.

O ambiente virtual resolve isso criando uma instalação Python isolada por projeto — cada um tem suas próprias bibliotecas, nas suas próprias versões, sem interferir nos outros.

Criando um ambiente virtual

O Python já vem com a ferramenta venv incluída, sem precisar instalar nada:

# Cria o ambiente virtual na pasta "venv"
python -m venv venv

Isso cria uma pasta chamada venv no diretório atual com uma cópia isolada do Python e um gerenciador de pacotes próprio.

Ativando o ambiente

Criar não é suficiente — você precisa ativar antes de usar:

# Linux / macOS
source venv/bin/activate
 
# Windows (Prompt de Comando)
venv\Scripts\activate.bat
 
# Windows (PowerShell)
venv\Scripts\Activate.ps1

Após ativar, o terminal mostra o nome do ambiente entre parênteses:

(venv) $ python -m pip install django

Tudo que você instalar agora vai para dentro de venv/, não para o sistema.

Verificando que está no ambiente certo

# Mostra qual Python está sendo usado
which python        # Linux/macOS
where python        # Windows
 
# Deve apontar para dentro da pasta venv/:
# /seu-projeto/venv/bin/python

# Lista só os pacotes do ambiente atual
pip list

Salvando as dependências do projeto

Depois de instalar tudo que seu projeto precisa, salve a lista de dependências:

pip freeze > requirements.txt

O arquivo gerado tem este formato:

Django==5.0.6
Pillow==10.3.0
python-dotenv==1.0.1
whitenoise==6.6.0

Qualquer pessoa que clonar seu projeto pode recriar o mesmo ambiente rodando:

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

O arquivo requirements.txt vai para o repositório. A pasta venv/ nunca vai — adicione ao .gitignore.

Configurando o .gitignore

Crie ou edite o .gitignore na raiz do projeto:

venv/
__pycache__/
*.pyc
.env
db.sqlite3

Desativando o ambiente

deactivate

O terminal volta ao Python global do sistema.

Fluxo completo de um projeto novo

Este é o fluxo padrão que você vai repetir em todo projeto Python:

# 1. Cria a pasta do projeto
mkdir meu-projeto && cd meu-projeto
 
# 2. Cria e ativa o ambiente virtual
python -m venv venv
source venv/bin/activate  # ou venv\Scripts\activate no Windows
 
# 3. Instala as dependências
pip install django pillow python-dotenv
 
# 4. Salva as dependências
pip freeze > requirements.txt
 
# 5. Inicia o repositório
git init
echo "venv/" >> .gitignore
echo ".env" >> .gitignore
git add .
git commit -m "setup inicial"

Erros comuns

Esqueceu de ativar antes de instalar

# Se você rodar pip install sem ativar:
pip install django   # vai para o Python global — problema
 
# Sempre ative primeiro:
source venv/bin/activate
pip install django   # vai para o venv — correto

Commitar a pasta venv/ por acidente

# Se já commitou, remova do rastreamento sem apagar o arquivo:
git rm -r --cached venv/
echo "venv/" >> .gitignore
git commit -m "remove venv do rastreamento"

requirements.txt desatualizado

Toda vez que instalar ou remover uma biblioteca, rode pip freeze > requirements.txt de novo e commite o arquivo atualizado.

Próximos passos

Com o ambiente virtual no lugar, você tem uma base sólida para qualquer projeto Python. O próximo passo é aprender a organizar o código dentro desse projeto — e é exatamente o que os tutoriais de estruturas de dados e POO cobrem.