---
title: "Poetry: O que É e Como Funciona | Python Brasil"
url: "https://python.dev.br/glossario/poetry/"
markdown_url: "https://python.dev.br/glossario/poetry.MD"
description: "Aprenda Poetry em Python: gerenciamento de dependencias, ambientes virtuais, publicacao de pacotes, pyproject.toml e boas praticas para projetos modernos."
date: "2026-02-28"
author: ""
---

# Poetry: O que É e Como Funciona | Python Brasil

Aprenda Poetry em Python: gerenciamento de dependencias, ambientes virtuais, publicacao de pacotes, pyproject.toml e boas praticas para projetos modernos.


## O que e Poetry?

**Poetry** e uma ferramenta moderna de gerenciamento de dependencias e empacotamento para projetos Python. Ela resolve varios problemas historicos do ecossistema Python ao unificar em uma unica ferramenta a gestao de dependencias, ambientes virtuais, build e publicacao de pacotes. Em vez de lidar com `pip`, `virtualenv`, `setup.py` e `requirements.txt` separadamente, o Poetry centraliza tudo no arquivo `pyproject.toml`.

Poetry garante **builds reprodutiveis** atraves do arquivo `poetry.lock`, que registra as versoes exatas de todas as dependencias e sub-dependencias instaladas.

## Instalacao

```python
# Instalacao recomendada (via pipx)
# pipx install poetry

# Ou via script oficial
# curl -sSL https://install.python-poetry.org | python3 -

# Verificar instalacao
# poetry --version

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

## Criando um Projeto

```python
# Criar novo projeto
# poetry new meu-projeto

# Estrutura gerada:
# meu-projeto/
#   pyproject.toml
#   README.md
#   meu_projeto/
#     __init__.py
#   tests/
#     __init__.py

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

## O Arquivo pyproject.toml

```toml
# pyproject.toml
# [tool.poetry]
# name = "minha-api"
# version = "1.0.0"
# description = "API REST para gerenciamento de tarefas"
# authors = ["Ana Silva <ana@email.com>"]
# license = "MIT"
# readme = "README.md"
# packages = [{include = "minha_api"}]
#
# [tool.poetry.dependencies]
# python = "^3.11"
# fastapi = "^0.109.0"
# uvicorn = {version = "^0.27.0", extras = ["standard"]}
# sqlalchemy = "^2.0"
# pydantic = "^2.5"
#
# [tool.poetry.group.dev.dependencies]
# pytest = "^8.0"
# pytest-cov = "^4.1"
# black = "^24.1"
# mypy = "^1.8"
# ruff = "^0.2"
#
# [tool.poetry.scripts]
# minha-api = "minha_api.cli:main"
#
# [build-system]
# requires = ["poetry-core"]
# build-backend = "poetry.core.masonry.api"
```

## Gerenciamento de Dependencias

```python
# Adicionar dependencia
# poetry add fastapi
# poetry add sqlalchemy@^2.0
# poetry add "uvicorn[standard]"

# Adicionar dependencia de desenvolvimento
# poetry add --group dev pytest black mypy

# Remover dependencia
# poetry remove flask

# Atualizar dependencias
# poetry update              # atualiza todas
# poetry update fastapi      # atualiza apenas fastapi

# Ver dependencias instaladas
# poetry show
# poetry show --tree          # arvore de dependencias
# poetry show --outdated      # dependencias desatualizadas

# Instalar dependencias do lock file
# poetry install              # todas
# poetry install --without dev  # sem dependencias de desenvolvimento
```

## Ambiente Virtual

```python
# Poetry cria e gerencia o virtualenv automaticamente

# Ver informacoes do ambiente
# poetry env info

# Ativar o shell do virtualenv
# poetry shell

# Executar comando no virtualenv sem ativar
# poetry run python script.py
# poetry run pytest
# poetry run uvicorn main:app --reload

# Listar ambientes virtuais
# poetry env list

# Remover ambiente virtual
# poetry env remove python3.11

# Usar versao especifica do Python
# poetry env use python3.12
```

## Scripts e Comandos

```python
# Definir scripts no pyproject.toml
# [tool.poetry.scripts]
# minha-cli = "minha_api.cli:main"
# servidor = "minha_api.server:start"

# arquivo: minha_api/cli.py
import argparse

def main():
    """Ponto de entrada da CLI."""
    parser = argparse.ArgumentParser(description='Minha API CLI')
    parser.add_argument('comando', choices=['iniciar', 'migrar', 'seed'])
    args = parser.parse_args()

    if args.comando == 'iniciar':
        print('Iniciando servidor...')
    elif args.comando == 'migrar':
        print('Executando migrations...')
    elif args.comando == 'seed':
        print('Populando banco de dados...')

# Apos `poetry install`, o comando fica disponivel:
# minha-cli iniciar
```

## O Arquivo poetry.lock

```python
# O poetry.lock garante reproducibilidade

# Gerar/atualizar o lock file
# poetry lock

# Instalar exatamente as versoes do lock
# poetry install

# IMPORTANTE: commite o poetry.lock no controle de versao!
# Isso garante que todos os desenvolvedores e ambientes
# de deploy usem exatamente as mesmas versoes.

# Verificar integridade
# poetry check
```

## Publicacao de Pacotes

```python
# Build do pacote
# poetry build
# Gera dist/minha_api-1.0.0.tar.gz e dist/minha_api-1.0.0-py3-none-any.whl

# Configurar repositorio (PyPI)
# poetry config pypi-token.pypi meu-token-do-pypi

# Publicar no PyPI
# poetry publish

# Build e publicar em um unico comando
# poetry publish --build

# Publicar em repositorio privado
# poetry config repositories.meu-repo https://meu-pypi.empresa.com/simple/
# poetry publish -r meu-repo
```

## Configuracao de Ferramentas no pyproject.toml

```toml
# O pyproject.toml tambem configura outras ferramentas

# [tool.pytest.ini_options]
# testpaths = ["tests"]
# python_files = "test_*.py"
# addopts = "-v --cov=minha_api --cov-report=term-missing"
#
# [tool.black]
# line-length = 88
# target-version = ['py311']
#
# [tool.mypy]
# python_version = "3.11"
# strict = true
# warn_return_any = true
#
# [tool.ruff]
# line-length = 88
# select = ["E", "F", "I", "N", "W"]
```

## Migrando de pip/requirements.txt

```python
# Importar requirements.txt existente
# cat requirements.txt | xargs poetry add

# Script para migrar
import subprocess

def migrar_requirements(arquivo: str = 'requirements.txt'):
    """Migra dependencias de requirements.txt para Poetry."""
    with open(arquivo) as f:
        deps = [
            linha.strip()
            for linha in f
            if linha.strip() and not linha.startswith('#')
        ]

    for dep in deps:
        print(f'Adicionando: {dep}')
        subprocess.run(['poetry', 'add', dep])

# Exportar para requirements.txt (compatibilidade)
# poetry export -f requirements.txt -o requirements.txt --without-hashes
```

## Erros Comuns

O erro mais frequente e nao committar o `poetry.lock` no repositorio, perdendo a garantia de reproducibilidade. Outro erro e misturar `pip install` com `poetry add`, instalando dependencias fora do controle do Poetry. Tambem e comum esquecer de executar `poetry install` apos clonar um repositorio, ou nao usar `poetry run` para executar scripts, usando o Python global em vez do ambiente virtual do projeto. Usar versoes de Python incompativeis com a restricao definida no `pyproject.toml` tambem gera erros.

## Boas Praticas

Sempre commite o `poetry.lock`. Configure `virtualenvs.in-project true` para manter o virtualenv dentro do projeto. Use grupos de dependencias (dev, test, docs) para organizar dependencias. Exporte `requirements.txt` apenas para ambientes que exigem compatibilidade. Use `poetry check` para validar o `pyproject.toml`. Mantenha as restricoes de versao razoaveis — `^` permite atualizacoes compativeis, `~` permite apenas patches.

## Quando Usar

Poetry e recomendado para qualquer projeto Python novo, especialmente quando envolve trabalho em equipe, deploy em multiplos ambientes ou publicacao de pacotes. Para scripts simples e de uso pessoal, `pip` com `venv` pode ser suficiente. A curva de aprendizado do Poetry e rapida e os beneficios de reproducibilidade e organizacao compensam rapidamente o investimento inicial.