Poetry: projetos, dependências e lockfile

O que o Poetry resolve

O pip instala. O Poetry gerencia: declara as dependências do projeto no pyproject.toml, resolve a árvore completa de dependências indiretas, grava as versões exatas em poetry.lock e cria o ambiente virtual para você. Dois colegas que rodam poetry install obtêm exatamente os mesmos pacotes.

Um ponto de atenção da versão 2: o Poetry passou a respeitar a seção [project] do pyproject.toml, que é o padrão da comunidade (PEP 621). O comando poetry shell foi movido para um plugin, e o substituto é poetry env activate.

Instalar

O caminho que eu recomendo é instalar o Poetry com o pipx, para que ele fique isolado:

pipx install poetry
poetry --version

O instalador oficial também funciona:

curl -sSL https://install.python-poetry.org | python3 -

Criar um projeto

O Poetry cria a estrutura e o pyproject.toml. Nas versões atuais, o código já vai para a pasta src/ por padrão, que é o layout que eu recomendo no capítulo de empacotamento. A opção --src, que você ainda vê em tutoriais antigos, está sendo descontinuada justamente por ter virado o comportamento padrão:

poetry new meu-projeto
cd meu-projeto

Para transformar uma pasta existente em projeto Poetry, use poetry init, que faz perguntas no terminal. Depois de poetry add requests e poetry add --group dev pytest, o arquivo fica assim. Repare que o grupo de desenvolvimento vai para [dependency-groups], o mesmo padrão que o uv usa, e que os campos de autor vêm com valores de exemplo para você trocar:

[project]
name = "meu-projeto"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests (>=2.34.2,<3.0.0)"
]

[tool.poetry]
packages = [{include = "meu_projeto", from = "src"}]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

[dependency-groups]
dev = [
    "pytest (>=9.1.1,<10.0.0)"
]

Os comandos do dia a dia

poetry add requests
poetry add --group dev pytest
poetry remove requests
poetry install
poetry sync
poetry run python -m meu_projeto
poetry run pytest
poetry show --tree
poetry update
poetry lock

A diferença entre install e sync: o install garante que o necessário esteja instalado. O sync faz o ambiente ficar idêntico ao lockfile, removendo o que sobrar.

Ativar o ambiente

Você pode sempre usar poetry run, sem ativar nada. Se preferir ativar o ambiente na sua sessão, no Poetry 2 o comando imprime a instrução de ativação, e você a executa. No macOS e no Linux, eval $(poetry env activate) faz as duas coisas de uma vez:

poetry env activate
poetry env info --path
poetry env use 3.13

. /caminho/do/projeto/.venv/bin/activate

O bloco acima mostra o que o primeiro comando imprime em um projeto com .venv dentro da pasta.

Para que o Poetry crie o .venv dentro da pasta do projeto (o que os editores detectam sozinhos), configure uma vez:

poetry config virtualenvs.in-project true

Ler o pyproject.toml pelo Python

Desde o Python 3.11 existe o módulo tomllib na biblioteca padrão, que lê TOML:

import tomllib

texto = """
[project]
name = "meu-projeto"
dependencies = ["requests>=2.32"]
"""

dados = tomllib.loads(texto)
print(dados["project"]["name"])
print(dados["project"]["dependencies"])

meu-projeto
['requests>=2.32']

Faça commit do poetry.lock

Em aplicações, o poetry.lock vai para o Git. É ele que garante que o seu servidor de produção instale o mesmo que você testou. Em bibliotecas publicadas, a discussão é mais sutil, e eu volto a ela no capítulo de empacotamento.