Poetry & PDM
Poetry e PDM são gerenciadores de projetos Python completos que lidam com resolução de dependências, arquivos de lock, ambientes virtuais e publicação. Ambos usam pyproject.toml como a única fonte de verdade.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
# Poetry
curl -sSL https://install.python-poetry.org | python3 -
poetry new myapp
poetry add fastapi pydantic
poetry run pytest
# PDM
pip install pdm
pdm init
pdm add fastapi pydantic
pdm run pytestQuando usar isso:
- Equipe já padronizada em Poetry ou PDM
- Você precisa de fluxos de trabalho de build e publicação integrados
- Grupos de dependências (dev, docs, test) com garantias de arquivo de lock
- Migrando de
requirements.txtpara empacotamento moderno
Exemplo de Trabalho
# Conceitos compartilhados de pyproject.toml (Poetry ou PDM)
[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = ["fastapi>=0.115", "pydantic>=2"]
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9"]# Fluxo de trabalho do Poetry
poetry install --with dev
poetry run uvicorn myapp.main:app
# Fluxo de trabalho do PDM
pdm install -G dev
pdm run uvicorn myapp.main:appO que isso demonstra:
- Ambas as ferramentas leem metadados PEP 621
[project] - Arquivos de lock (
poetry.lock/pdm.lock) fixam versões exatas runexecuta comandos dentro do ambiente gerenciado- Grupos de desenvolvimento são instalados separadamente das dependências de produção
Mergulho Profundo
Como Funciona
- Poetry cria um
.venv(ou usa um existente), resolve dependências, gravapoetry.locke pode construir/publicar wheels. - PDM suporta PEP 582 (
__pypackages__) ou.venvtradicional, resolve viapdm.locke segue os padrões PEP de perto. - Ambos resolvem dependências transitivas e detectam conflitos antes da instalação.
- Arquivos de lock são regenerados quando as restrições de
pyproject.tomlmudam.
Comparativo de Recursos
| Recurso | Poetry | PDM |
|---|---|---|
| Arquivo de Lock | poetry.lock | pdm.lock |
| Localização do Venv | .venv (configurável) | .venv ou __pypackages__ |
| Backend de Build | poetry-core | pdm-backend |
| Publicar | poetry publish | pdm publish |
| Velocidade | Moderada | Moderada |
| Nativo PEP 621 | Sim (2.x+) | Sim |
Notas de Python
# Poetry: exportar para Docker/CI sem Poetry instalado
poetry export -f requirements.txt --output requirements.txt --without-hashes
# PDM: usar uv como backend de instalação para velocidade
pdm config install.use_uv trueArmadilhas
- Comprometer versões diferentes do arquivo de lock - CI e local divergem. Correção: comprometer
poetry.lock/pdm.lock; executar a instalação com o equivalente a--frozen. - Divergência de configuração entre Poetry 1.x e 2.x - blocos
[tool.poetry]vs[project]diferem. Correção: migrar para o layout PEP 621 do Poetry 2.x para novos projetos. __pypackages__do PDM e IDEs - editores podem não encontrar pacotes. Correção: usar o modo.venv(pdm config python.use_venv true) para compatibilidade com IDEs.- Instalação global de ferramentas em CI - lento e sem versão fixada. Correção: usar
pipx install poetryou a Ação GitHub oficial com uma versão fixada. - Misturar Poetry e uv em um único repositório - dois arquivos de lock lutam um contra o outro. Correção: escolher uma toolchain por projeto.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| uv | Novos projetos, prioridade de velocidade | Mandato da equipe para Poetry |
| pip + pip-tools | Dependências mínimas, sem etapa de build | Árvores de dependência complexas |
| Hatch | Builds simples, sem resolvedor | Você precisa de um gerenciador de projetos completo |
FAQs
Novos projetos devem usar Poetry ou uv?
uv é mais rápido e simples para a maioria das equipes. Escolha Poetry quando precisar do seu fluxo de trabalho de publicação maduro e a equipe já o conhece.
Poetry e PDM podem ler o mesmo pyproject.toml?
Ambos suportam PEP 621 [project], mas seções específicas da ferramenta ([tool.poetry], [tool.pdm]) diferem. Padronize em uma ferramenta por repositório.
Como funcionam os grupos de dependências no Poetry?
[dependency-groups] (Poetry 2.x) ou [tool.poetry.group.dev.dependencies] para pacotes apenas de desenvolvimento. Instale com poetry install --with dev.
O PDM requer um venv?
Não. PDM pode usar pacotes locais PEP 582. Para suporte a IDE, ative o modo venv.
Como atualizo todas as dependências?
Poetry: poetry update. PDM: pdm update. Ambos regeneram o arquivo de lock com as versões compatíveis mais recentes.
Posso migrar de requirements.txt?
Poetry: poetry add $(cat requirements.txt). PDM: pdm import requirements.txt. Em seguida, comprometa o arquivo de lock.
Como executar scripts sem lembrar dos caminhos?
Defina [project.scripts] ou [tool.poetry.scripts] e use poetry run <script> ou pdm run <script>.
Quais versões do Python eles suportam?
Ambos respeitam requires-python em pyproject.toml. Use poetry env use 3.14 ou pdm use 3.14 para fixar o interpretador.
Como publicar no PyPI?
Poetry: poetry build && poetry publish. PDM: pdm build && pdm publish. Configure tokens via variáveis de ambiente, não em arquivos.
Arquivos de lock são portáteis entre plataformas?
Na maioria das vezes sim, mas wheels específicos da plataforma podem diferir. A CI deve gerar ou verificar arquivos de lock em cada sistema operacional de destino.
Relacionados
- uv - A Toolchain Rápida - alternativa mais rápida
- pyproject.toml Explicado - referência de configuração
- Resolução de Dependências e Arquivos de Lock - mergulho profundo em pinning
- Melhores Práticas de Ambientes - convenções de equipe
Versões das Pilhas: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.