Poetry para Python: Guia Completo
Aprenda a usar Poetry para gerenciar dependências e ambientes virtuais em Python. Instalação, configuração, comandos e publicação de pacotes
Introdução
O Poetry é um gerenciador moderno de dependências e empacotamento para Python. Ele resolve problemas que o pip e o requirements.txt não tratam bem, como resolução de conflitos entre versões de bibliotecas, separação de dependências de desenvolvimento e criação de ambientes virtuais automáticos.
Neste guia, vamos instalar o Poetry, criar projetos, gerenciar dependências e entender por que ele se tornou a ferramenta preferida de muitos desenvolvedores Python.
Por que usar Poetry em vez de pip?
O pip com requirements.txt funciona, mas tem limitações:
- Não resolve conflitos de dependências automaticamente
- Não diferencia dependências de produção e desenvolvimento nativamente
- Não trava versões de subdependências (dependências das dependências)
- Requer gerenciar o ambiente virtual separadamente
O Poetry resolve todos esses problemas com um único arquivo pyproject.toml e um lock file que garante builds reprodutíveis.
Instalação
A forma recomendada de instalar o Poetry é pelo instalador oficial:
curl -sSL https://install.python-poetry.org | python3 -
No Windows (PowerShell):
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
Adicione o Poetry ao PATH seguindo as instruções exibidas após a instalação. Verifique:
poetry --version
Autocompletar no terminal
Para Bash:
poetry completions bash >> ~/.bash_completion
Para Zsh:
poetry completions zsh > ~/.zfunc/_poetry
Criando um novo projeto
poetry new meu-projeto
cd meu-projeto
Estrutura gerada:
meu-projeto/
meu_projeto/
__init__.py
tests/
__init__.py
pyproject.toml
README.md
O pyproject.toml gerado contém:
[tool.poetry]
name = "meu-projeto"
version = "0.1.0"
description = ""
authors = ["Seu Nome <seu@email.com>"]
readme = "README.md"
[tool.poetry.dependencies]
python = "^3.10"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Inicializando em um projeto existente
Se você já tem um projeto:
cd projeto-existente
poetry init
O Poetry faz perguntas interativas para gerar o pyproject.toml.
Gerenciando dependências
Adicionando dependências
# Dependencia de producao
poetry add flask
poetry add sqlalchemy
# Dependencia de desenvolvimento
poetry add --group dev pytest
poetry add --group dev black ruff
# Versao especifica
poetry add django@^5.0
poetry add requests@~2.31
O operador ^ aceita atualizações que não quebram a API (ex: ^5.0 aceita 5.1, 5.2, mas não 6.0). O operador ~ aceita apenas patches (ex: ~2.31 aceita 2.31.1, mas não 2.32).
Removendo dependências
poetry remove flask
poetry remove --group dev black
Atualizando dependências
# Atualizar todas
poetry update
# Atualizar uma especifica
poetry update requests
# Ver dependencias desatualizadas
poetry show --outdated
O arquivo poetry.lock
Quando você adiciona uma dependência, o Poetry gera o poetry.lock. Este arquivo registra a versão exata de cada biblioteca e todas as subdependências.
Sempre faça commit do poetry.lock no Git. Isso garante que todos na equipe usem exatamente as mesmas versões.
Para instalar a partir do lock file (exatamente as versões registradas):
poetry install
Ambientes virtuais
O Poetry cria e gerencia ambientes virtuais automaticamente. Para executar comandos dentro do ambiente:
# Executar um script
poetry run python meu_script.py
# Executar testes
poetry run pytest
# Abrir shell dentro do ambiente
poetry shell
Configurações do ambiente virtual
# Criar o venv dentro do projeto (recomendado para IDEs)
poetry config virtualenvs.in-project true
# Ver onde o venv esta
poetry env info --path
# Listar ambientes disponiveis
poetry env list
# Remover um ambiente
poetry env remove python3.12
Com virtualenvs.in-project true, o Poetry cria a pasta .venv dentro do projeto, facilitando a detecção por editores como VS Code e PyCharm.
Scripts personalizados
Defina scripts no pyproject.toml:
[tool.poetry.scripts]
servidor = "meu_projeto.main:iniciar"
Isso cria um comando executável servidor que chama a função iniciar() do módulo meu_projeto.main.
Grupos de dependências
Organize dependências por contexto:
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
ruff = "^0.4"
[tool.poetry.group.docs.dependencies]
mkdocs = "^1.6"
mkdocs-material = "^9.5"
[tool.poetry.group.test.dependencies]
pytest-cov = "^5.0"
factory-boy = "^3.3"
Instale apenas produção (sem grupos de dev):
poetry install --without dev,docs
Migrando de pip para Poetry
Se você já tem um requirements.txt:
# Inicialize o projeto
poetry init
# Adicione as dependencias do requirements.txt
cat requirements.txt | xargs poetry add
Ou adicione manualmente as dependências principais. O Poetry resolve as subdependências automaticamente.
Integrando com ferramentas
pytest
[tool.pytest.ini_options]
testpaths = ["tests"]
poetry run pytest
Black e Ruff
[tool.black]
line-length = 88
[tool.ruff]
line-length = 88
select = ["E", "F", "I"]
Configuração completa no pyproject.toml
Uma das vantagens do Poetry é centralizar toda a configuração no pyproject.toml, eliminando arquivos como setup.cfg, tox.ini e pytest.ini.
Publicando pacotes com Poetry
O Poetry simplifica a publicação no PyPI:
# Build
poetry build
# Publicar no TestPyPI
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi
# Publicar no PyPI oficial
poetry publish
Comandos essenciais resumidos
poetry new projeto # Criar projeto
poetry init # Inicializar em projeto existente
poetry add pacote # Adicionar dependencia
poetry remove pacote # Remover dependencia
poetry install # Instalar dependencias
poetry update # Atualizar dependencias
poetry show # Listar dependencias
poetry run comando # Executar dentro do venv
poetry shell # Abrir shell no venv
poetry build # Gerar pacote
poetry publish # Publicar no PyPI
Conclusão
O Poetry moderniza o gerenciamento de dependências em Python, resolvendo problemas históricos do pip e do requirements.txt. O lock file garante reprodutibilidade, os grupos organizam dependências por contexto e a integração com o pyproject.toml centraliza toda a configuração. Se você trabalha em equipe ou mantém projetos com muitas dependências, o Poetry é um investimento que se paga rapidamente em tempo economizado e problemas evitados.