Ambientes virtuais em Python: venv e pip explicados

O problema que o venv resolve

Imagine dois projetos Python no seu computador:

• Projeto A precisa do Flask 2.0
• Projeto B precisa do Flask 3.0

Se você instalar tudo globalmente, um vai quebrar o outro. Ambientes virtuais criam uma instalação isolada de Python para cada projeto.

projeto_a/
  venv/        ← Flask 2.0 aqui
  app.py

projeto_b/
  venv/        ← Flask 3.0 aqui
  app.py

Cada projeto tem suas próprias bibliotecas, sem conflito.

Criando um ambiente virtual

# Entrar na pasta do projeto
cd meu_projeto

# Criar o ambiente virtual
python3 -m venv venv

Isso cria uma pasta venv/ com uma cópia isolada do Python.

Ativando o ambiente

# macOS / Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

Quando ativado, você verá (venv) no início do terminal:

(venv) $ python --version
Python 3.12.0

Desativando

deactivate

pip: instalando bibliotecas

Com o ambiente ativado, use pip para instalar pacotes:

# Instalar um pacote
pip install flask

# Instalar versao especifica
pip install flask==3.0.0

# Instalar versao minima
pip install flask>=3.0

# Instalar varios de uma vez
pip install flask pymongo requests

Comandos úteis do pip

# Ver pacotes instalados
pip list

# Detalhes de um pacote
pip show flask

# Atualizar um pacote
pip install --upgrade flask

# Desinstalar
pip uninstall flask

requirements.txt: compartilhando dependências

O requirements.txt é a lista de tudo que seu projeto precisa:

Gerando o arquivo

pip freeze > requirements.txt

O resultado é algo assim:

Flask==3.0.3
Jinja2==3.1.4
pymongo==4.8.0
requests==2.32.3

Instalando a partir do arquivo

Quando outra pessoa (ou você em outra máquina) clona o projeto:

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

Tudo instalado com as mesmas versões. Sem surpresas.

O .gitignore

A pasta venv/ nunca deve ir para o repositório Git. Ela é pesada e específica do seu sistema. Adicione ao .gitignore:

venv/
__pycache__/
*.pyc
.env

O que vai para o repositório é o requirements.txt, não a pasta venv/.

Fluxo completo de um projeto

# 1. Criar pasta do projeto
mkdir meu_site && cd meu_site

# 2. Criar ambiente virtual
python3 -m venv venv

# 3. Ativar
source venv/bin/activate

# 4. Instalar dependencias
pip install flask pymongo

# 5. Salvar dependencias
pip freeze > requirements.txt

# 6. Trabalhar no projeto
python app.py

# 7. Ao terminar
deactivate

Problemas comuns

"pip não encontrado"

# Use pip3 em vez de pip
pip3 install flask

# Ou garanta que o venv esta ativado
source venv/bin/activate

"ModuleNotFoundError" mesmo após instalar

Provavelmente você instalou fora do venv. Verifique:

# Qual Python esta sendo usado?
which python

# Deve mostrar algo como:
# /caminho/do/projeto/venv/bin/python

# Se mostrar /usr/bin/python, o venv nao esta ativado

Recriando o ambiente

Se algo deu errado, basta deletar e recriar:

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

venv vs outras ferramentas

Para a maioria dos projetos, venv + pip + requirements.txt é tudo que você precisa. Comece simples.

Resumo

Ambientes virtuais são o primeiro passo para trabalhar de forma profissional com Python. Crie um para cada projeto e nunca mais tenha conflitos de versão.