Ambientes Virtuais Python: venv e Poetry

Se você já teve problemas com versões conflitantes de bibliotecas em Python, sabe a dor de cabeça que isso causa. Ambientes virtuais resolvem esse problema isolando as dependências de cada projeto. Neste guia, a gente vai explorar as três ferramentas mais populares: venv, virtualenv e Poetry.

Por que Usar Ambientes Virtuais?

Sem ambientes virtuais, todas as bibliotecas são instaladas globalmente no sistema. Isso causa problemas quando:

O Projeto A precisa de Django 4.2 e o Projeto B precisa de Django 5.0
Uma atualização de biblioteca quebra outro projeto
Você não sabe quais dependências seu projeto realmente precisa
Você precisa reproduzir o ambiente em outra máquina ou no servidor

# Exemplo do problema (sem ambiente virtual):
# pip install django==4.2  <- Projeto A precisa dessa versão
# pip install django==5.0  <- Projeto B sobrescreve! Projeto A quebra!

# Com ambientes virtuais, cada projeto tem suas próprias dependências
# isoladas, sem interferir um no outro.

venv: O Padrão do Python

venv já vem incluído no Python 3.3+ e é a forma mais simples de criar ambientes virtuais.

Criando e ativando

# Criar o ambiente virtual
# python -m venv .venv

# Ativar no Linux/macOS
# source .venv/bin/activate

# Ativar no Windows (CMD)
# .venv\Scripts\activate

# Ativar no Windows (PowerShell)
# .venv\Scripts\Activate.ps1

# Quando ativado, o prompt muda:
# (.venv) usuario@maquina:~/projeto$

Usando o ambiente virtual

# Instalar dependências (dentro do ambiente ativado)
# pip install flask requests pandas

# Ver pacotes instalados
# pip list

# Exportar dependências para requirements.txt
# pip freeze > requirements.txt

# Instalar a partir do requirements.txt (outra máquina)
# pip install -r requirements.txt

# Desativar o ambiente virtual
# deactivate

Exemplo prático com venv

# Fluxo completo de um projeto com venv

# 1. Criar o projeto
# mkdir meu-projeto && cd meu-projeto

# 2. Criar o ambiente virtual
# python -m venv .venv

# 3. Ativar
# source .venv/bin/activate  (Linux/macOS)

# 4. Instalar dependências
# pip install flask sqlalchemy python-dotenv

# 5. Gerar requirements.txt
# pip freeze > requirements.txt

# 6. Adicionar .venv ao .gitignore
# echo ".venv/" >> .gitignore

Arquivo requirements.txt

# requirements.txt - gerado com pip freeze
# Flask==3.0.2
# SQLAlchemy==2.0.27
# python-dotenv==1.0.1
# Werkzeug==3.0.1
# Jinja2==3.1.3

# Você também pode ter um requirements-dev.txt para desenvolvimento:
# -r requirements.txt
# pytest==8.0.0
# pytest-cov==4.1.0
# black==24.1.0
# flake8==7.0.0

Script para automatizar setup com venv

#!/usr/bin/env python3
"""Script para configurar o ambiente de desenvolvimento."""

import subprocess
import sys
import os
from pathlib import Path

def setup_projeto():
    projeto_dir = Path(".")
    venv_dir = projeto_dir / ".venv"

    # Criar venv se não existir
    if not venv_dir.exists():
        print("Criando ambiente virtual...")
        subprocess.run([sys.executable, "-m", "venv", str(venv_dir)])
        print("Ambiente virtual criado!")

    # Determinar o pip do venv
    if os.name == "nt":  # Windows
        pip = str(venv_dir / "Scripts" / "pip")
    else:  # Linux/macOS
        pip = str(venv_dir / "bin" / "pip")

    # Atualizar pip
    print("Atualizando pip...")
    subprocess.run([pip, "install", "--upgrade", "pip"])

    # Instalar dependências
    requirements = projeto_dir / "requirements.txt"
    if requirements.exists():
        print("Instalando dependências...")
        subprocess.run([pip, "install", "-r", str(requirements)])
    else:
        print("requirements.txt não encontrado.")

    # Instalar dependências de desenvolvimento
    requirements_dev = projeto_dir / "requirements-dev.txt"
    if requirements_dev.exists():
        print("Instalando dependências de desenvolvimento...")
        subprocess.run([pip, "install", "-r", str(requirements_dev)])

    print("\nSetup concluído!")
    print(f"Ative o ambiente com: source {venv_dir}/bin/activate")

if __name__ == "__main__":
    setup_projeto()

virtualenv: A Alternativa Clássica

virtualenv é mais antigo que venv e tem algumas vantagens como ser mais rápido e suportar versões mais antigas de Python.

# Instalação
# pip install virtualenv

# Criar ambiente virtual
# virtualenv .venv

# Criar com versão específica de Python
# virtualenv -p python3.11 .venv

# Ativar (mesmo que venv)
# source .venv/bin/activate

# virtualenv cria ambientes mais rápido que venv
# e tem opção de --copies e --clear

Poetry: Gerenciamento Moderno

Poetry é a ferramenta mais moderna e completa para gerenciamento de dependências em Python. Ele resolve dependências automaticamente, gera lock files e gerencia o ambiente virtual pra você.

Instalação do Poetry

# Instalação recomendada (Linux/macOS)
# curl -sSL https://install.python-poetry.org | python3 -

# Verificar instalação
# poetry --version

# Configurar para criar .venv dentro do projeto
# poetry config virtualenvs.in-project true

Criando um projeto com Poetry

# Criar novo projeto
# poetry new meu-projeto

# Estrutura criada:
# meu-projeto/
# ├── pyproject.toml
# ├── README.md
# ├── meu_projeto/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

# Ou inicializar em projeto existente
# cd meu-projeto-existente
# poetry init

pyproject.toml

O pyproject.toml é o coração do Poetry — ele substitui setup.py, requirements.txt e setup.cfg:

# pyproject.toml
# [tool.poetry]
# name = "meu-projeto"
# version = "0.1.0"
# description = "Um projeto Python incrível"
# authors = ["Maria Silva <maria@email.com>"]
# readme = "README.md"
# python = "^3.10"
#
# [tool.poetry.dependencies]
# python = "^3.10"
# flask = "^3.0"
# sqlalchemy = "^2.0"
# pydantic = "^2.5"
#
# [tool.poetry.group.dev.dependencies]
# pytest = "^8.0"
# pytest-cov = "^4.1"
# black = "^24.0"
# ruff = "^0.2"
# mypy = "^1.8"
#
# [build-system]
# requires = ["poetry-core"]
# build-backend = "poetry.core.masonry.api"

Comandos Essenciais do Poetry

# Adicionar dependências
# poetry add flask
# poetry add sqlalchemy pydantic
# poetry add "django>=4.2,<5.0"

# Adicionar dependência de desenvolvimento
# poetry add --group dev pytest black ruff

# Remover dependência
# poetry remove flask

# Instalar todas as dependências
# poetry install

# Instalar sem dependências de dev (produção)
# poetry install --without dev

# Atualizar dependências
# poetry update
# poetry update flask  # atualizar pacote específico

# Ver dependências instaladas
# poetry show
# poetry show --tree  # em formato de árvore

# Rodar comandos dentro do ambiente virtual
# poetry run python meu_script.py
# poetry run pytest
# poetry run flask run

# Ativar o shell do ambiente virtual
# poetry shell

Exemplo prático com Poetry

# Fluxo completo de um projeto Flask com Poetry

# 1. Criar projeto
# poetry new minha-api && cd minha-api

# 2. Adicionar dependências
# poetry add flask flask-sqlalchemy python-dotenv

# 3. Adicionar dependências de dev
# poetry add --group dev pytest pytest-cov black ruff

# 4. Criar o app
# minha_api/app.py
from flask import Flask, jsonify

def create_app():
    app = Flask(__name__)

    @app.route("/")
    def index():
        return jsonify({"status": "online", "mensagem": "API funcionando!"})

    @app.route("/saude")
    def health_check():
        return jsonify({"status": "saudável"})

    return app

if __name__ == "__main__":
    app = create_app()
    app.run(debug=True)

Poetry Lock File

O poetry.lock garante que todos os desenvolvedores e o servidor de produção usem exatamente as mesmas versões:

# O poetry.lock é gerado automaticamente e deve ser commitado no git!
# Ele contém as versões exatas de todas as dependências e sub-dependências.

# Para instalar exatamente as versões do lock:
# poetry install

# Para atualizar o lock sem instalar:
# poetry lock

# Para verificar se o lock está atualizado:
# poetry check

Comparação: venv vs virtualenv vs Poetry

Aspecto	venv	virtualenv	Poetry
Instalação	Incluso no Python	pip install	Instalador próprio
Resolução de deps	Manual (pip)	Manual (pip)	Automática
Lock file	Não	Não	Sim (poetry.lock)
Grupos de deps	Não	Não	Sim (dev, test, etc.)
Publicar pacote	Não	Não	Sim
Scripts	Não	Não	Sim
Velocidade setup	Médio	Rápido	Médio
Curva aprendizado	Baixa	Baixa	Média

Boas Práticas

# 1. SEMPRE use ambientes virtuais - sem exceção!

# 2. Adicione o diretório do venv ao .gitignore
# .gitignore
# .venv/
# __pycache__/
# *.pyc
# .env

# 3. Documente como configurar o ambiente
# No README.md ou CONTRIBUTING.md do seu projeto

# 4. Use nomes consistentes para o ambiente
# .venv (recomendado - fica oculto e dentro do projeto)

# 5. Trave as versões em produção
# Em vez de flask>=3.0, use flask==3.0.2 em produção

# 6. Separe dependências de dev e produção
# requirements.txt para produção
# requirements-dev.txt para desenvolvimento
# Ou use grupos do Poetry

# 7. Atualize dependências regularmente
# Mas teste tudo depois de atualizar!

Dica Extra: pyenv para Gerenciar Versões do Python

# pyenv permite instalar e alternar entre versões do Python

# Instalação (Linux/macOS)
# curl https://pyenv.run | bash

# Listar versões disponíveis
# pyenv install --list

# Instalar uma versão
# pyenv install 3.12.1

# Definir versão global
# pyenv global 3.12.1

# Definir versão por projeto
# cd meu-projeto
# pyenv local 3.11.7

# Combinação perfeita: pyenv + Poetry
# pyenv install 3.12.1
# pyenv local 3.12.1
# poetry env use python3.12
# poetry install

Conclusão

A escolha entre as ferramentas depende do seu contexto:

Iniciante ou projeto simples: Use venv — já vem com Python e é fácil de usar
Projeto profissional/equipe: Use Poetry — gerenciamento completo e reproduzível
Compatibilidade com Python antigo: Use virtualenv

O mais importante é sempre usar algum tipo de isolamento. Instalar pacotes globalmente é receita para dor de cabeça. Escolha a ferramenta que faz mais sentido pro seu projeto e use-a consistentemente.