Python Poetry: Guia Moderno de Gerenciamento de Dependências e Empacotamento

Name

Soren Atelier

Updated on 12/02/2026

Gerenciar dependências em Python não deveria ser doloroso. Ainda assim, todo desenvolvedor Python já viveu este cenário: você clona um projeto, roda pip install -r requirements.txt e assiste aos conflitos de dependência se acumularem no terminal. O pacote A precisa da versão 1.x de uma biblioteca, o pacote B precisa da versão 2.x, e o pip instala aquela que ele resolver por último — quebrando silenciosamente um deles. Depois vêm horas de debug, tudo porque o pip não tem um mecanismo adequado de resolução de dependências e de lock file.

Esse problema se agrava em ambientes de equipe. Um desenvolvedor fixa versões exatas, outro usa intervalos soltos, e um terceiro esquece de atualizar o requirements.txt após instalar um novo pacote. Deploys falham. Testes passam localmente, mas quebram no CI. A causa raiz é sempre a mesma: o tooling padrão do Python trata o gerenciamento de dependências como um detalhe.

O Poetry resolve isso oferecendo uma única ferramenta que lida com resolução de dependências, gerenciamento de ambientes virtuais e publicação de pacotes. Ele usa um arquivo padronizado pyproject.toml, gera lock files determinísticos e resolve conflitos de dependências antes da instalação — não depois. Este guia cobre tudo, da instalação à publicação, com exemplos práticos para cada fluxo de trabalho.

O que é Python Poetry?

Poetry é uma ferramenta open-source de gerenciamento de dependências e empacotamento para Python. Criada por Sebastien Eustace em 2018, ela aborda o estado fragmentado do empacotamento em Python ao combinar várias funções em uma ferramenta coerente:

• Resolução de dependências: o Poetry analisa todas as dependências e suas subdependências para encontrar versões compatíveis antes de instalar qualquer coisa.
• Lock files: um arquivo poetry.lock registra as versões exatas de cada pacote instalado, garantindo builds reprodutíveis entre máquinas.
• Gerenciamento de ambientes virtuais: o Poetry cria e gerencia automaticamente ambientes virtuais isolados por projeto.
• Build e publicação de pacotes: o Poetry gera source distributions e wheels, e publica diretamente no PyPI ou em repositórios privados.
• Scaffolding de projeto: o Poetry gera estruturas de projeto com configuração correta no pyproject.toml.

O Poetry usa pyproject.toml como arquivo de configuração, seguindo os padrões PEP 518 e PEP 621. Isso substitui a combinação de setup.py, setup.cfg, requirements.txt e MANIFEST.in que projetos Python tradicionais exigem.

Instalando o Poetry

O Poetry fornece seu próprio instalador, que o isola das dependências do seu projeto, evitando conflitos de versão entre o Poetry e os pacotes do projeto.

Instalação recomendada (instalador oficial)

Linux, macOS e Windows (WSL):

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

Windows (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Após a instalação, adicione o Poetry ao seu PATH. O instalador imprime o caminho exato — normalmente $HOME/.local/bin no Linux/macOS ou %APPDATA%\Python\Scripts no Windows.

Verifique a instalação:

poetry --version

Instalação com pipx

Se você preferir usar o pipx (que também isola ferramentas de CLI):

pipx install poetry

Atualizando o Poetry

poetry self update

Para atualizar para uma versão específica:

poetry self update 1.8.0

Habilitando tab completion

O Poetry suporta completion para Bash, Zsh e Fish:

# Bash
poetry completions bash >> ~/.bash_completion
 
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
 
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

Criando um novo projeto

O Poetry oferece duas maneiras de iniciar um projeto: criar um do zero ou inicializar o Poetry em um projeto existente.

Novo projeto do zero

poetry new my-project

Isso gera a seguinte estrutura:

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

Para um layout flat de código-fonte (pacote na raiz):

poetry new --src my-project

Isso coloca o pacote dentro de um diretório src/:

my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── __init__.py

Inicializando em um projeto existente

Navegue até o diretório do projeto existente e execute:

cd existing-project
poetry init

O Poetry conduz um setup interativo, perguntando nome do pacote, versão, descrição, autor, compatibilidade de versão do Python e dependências. Você pode pressionar Enter para aceitar os padrões ou pular campos opcionais.

Para um setup não interativo:

poetry init --name my-package --description "A useful package" --author "Your Name <you@example.com>" --python "^3.9" --no-interaction

Entendendo o pyproject.toml

O arquivo pyproject.toml é a fonte única de verdade para a configuração do seu projeto. Aqui está um exemplo completo:

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = "A data processing library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/yourname/my-project"
repository = "https://github.com/yourname/my-project"
keywords = ["data", "processing", "analytics"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries",
]
 
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.31"
pydantic = ">=2.0,<3.0"
 
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.0"
ruff = "^0.3"
 
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
sphinx-rtd-theme = "^2.0"
 
[tool.poetry.scripts]
my-cli = "my_project.cli:main"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Sintaxe de restrições de versão

O Poetry usa uma sintaxe clara para restrições de versão:

A restrição com caret (^) é a mais comum e recomendada. Ela permite atualizações que não alteram o dígito mais à esquerda diferente de zero, seguindo princípios de semantic versioning.

Grupos de dependências

O Poetry organiza dependências em grupos, substituindo a necessidade de arquivos requirements separados:

• Dependências principais ([tool.poetry.dependencies]): necessárias para o pacote funcionar. São incluídas quando alguém instala seu pacote.
• Dependências de desenvolvimento ([tool.poetry.group.dev.dependencies]): ferramentas para desenvolvimento, testes e linting. Não são incluídas em pacotes publicados.
• Grupos customizados ([tool.poetry.group.docs.dependencies]): qualquer agrupamento adicional necessário, como ferramentas de documentação.

Adicionando e removendo dependências

Adicionando pacotes

Adicione um pacote às dependências principais:

poetry add pandas

Adicionar com restrição de versão:

poetry add "pandas>=2.0,<3.0"

Adicionar ao grupo de desenvolvimento:

poetry add --group dev pytest black ruff

Adicionar a um grupo customizado:

poetry add --group docs sphinx

Adicionar um pacote a partir de um repositório Git:

poetry add git+https://github.com/user/repo.git

Adicionar um pacote a partir de um branch ou tag específicos:

poetry add git+https://github.com/user/repo.git#branch-name
poetry add git+https://github.com/user/repo.git#v1.0.0

Adicionar uma dependência via caminho local:

poetry add ../my-local-package

Adicionar extras para um pacote:

poetry add "uvicorn[standard]"

Removendo pacotes

Remova um pacote:

poetry remove pandas

Remover de um grupo específico:

poetry remove --group dev black

Listando pacotes instalados

Ver todos os pacotes instalados:

poetry show

Ver detalhes de um pacote específico:

poetry show pandas

Mostrar a árvore de dependências:

poetry show --tree

Mostrar pacotes desatualizados:

poetry show --outdated

O lock file: poetry.lock

O arquivo poetry.lock é uma das funcionalidades mais importantes do Poetry. Quando você executa poetry install ou poetry add, o Poetry resolve todas as dependências e grava as versões exatas (incluindo todas as dependências transitivas) em poetry.lock.

Por que lock files importam

Sem um lock file, rodar pip install -r requirements.txt com restrições soltas pode produzir instalações diferentes em máquinas diferentes ou em momentos diferentes. Um lock file elimina essa aleatoriedade.

Considere este cenário:

[tool.poetry.dependencies]
requests = "^2.28"

Isso permite qualquer versão de 2.28.0 até 2.99.x. Sem um lock file, seu servidor de CI pode instalar 2.31.0 enquanto sua máquina local usa 2.28.2. O lock file fixa a versão exata em todos os ambientes.

Workflow do lock file

Faça commit do poetry.lock no controle de versão. Isso garante que cada desenvolvedor e cada deployment use versões de pacotes idênticas.

git add poetry.lock pyproject.toml
git commit -m "Add project dependencies"

Instale a partir do lock file (para instalações reprodutíveis):

poetry install

Isso instala exatamente as versões especificadas em poetry.lock, ignorando versões compatíveis mais novas.

Atualize o lock file quando você quiser versões mais recentes:

# Update all packages
poetry update
 
# Update a specific package
poetry update pandas
 
# Update the lock file without installing
poetry lock

Verifique a integridade do lock file:

poetry lock --check

Isso confirma que o lock file está consistente com pyproject.toml sem modificar nada.

Gerenciamento de ambiente virtual

O Poetry cria e gerencia automaticamente ambientes virtuais para seus projetos.

Comportamento padrão

Quando você roda poetry install ou poetry add, o Poetry cria um ambiente virtual se ele não existir. Por padrão, os ambientes são armazenados em um diretório de cache centralizado:

• Linux: ~/.cache/pypoetry/virtualenvs/
• macOS: ~/Library/Caches/pypoetry/virtualenvs/
• Windows: C:\Users\<user>\AppData\Local\pypoetry\Cache\virtualenvs\

Ambientes virtuais dentro do projeto

Muitos desenvolvedores preferem o ambiente virtual dentro do diretório do projeto (similar ao node_modules do Node.js). Configure isso globalmente:

poetry config virtualenvs.in-project true

Isso cria um diretório .venv na raiz do projeto, facilitando encontrar e tornando compatível com autodetecção em IDEs.

Executando comandos no ambiente virtual

Executar um único comando:

poetry run python my_script.py
poetry run pytest
poetry run black .

Ativar o shell do ambiente:

poetry shell

Isso inicia um novo shell com o ambiente virtual ativado. Saia com exit ou Ctrl+D.

Informações do ambiente

Ver detalhes do ambiente:

poetry env info

Listar todos os ambientes associados ao projeto:

poetry env list

Usar uma versão específica do Python:

poetry env use python3.11

Remover um ambiente:

poetry env remove python3.11

Instalando dependências

Instalação padrão

Instale todas as dependências (principais e de desenvolvimento):

poetry install

Instalação de produção

Instalar sem dependências de desenvolvimento:

poetry install --without dev

Instalar sem grupos específicos:

poetry install --without dev,docs

Instalando apenas grupos específicos

poetry install --only main
poetry install --only dev

Sincronizando o ambiente

Remover pacotes que não estão no lock file (instalação limpa):

poetry install --sync

Isso remove quaisquer pacotes que foram instalados manualmente ou que não estão mais no lock file, mantendo o ambiente exatamente de acordo com a configuração do projeto.

Build e publicação de pacotes

O Poetry simplifica todo o workflow de publicação de pacotes.

Fazendo build do seu pacote

poetry build

Isso cria tanto uma source distribution (.tar.gz) quanto uma wheel (.whl) no diretório dist/:

dist/
├── my_project-1.0.0.tar.gz
└── my_project-1.0.0-py3-none-any.whl

Publicando no PyPI

Primeiro, configure suas credenciais do PyPI:

poetry config pypi-token.pypi your-api-token

Depois publique:

poetry publish --build

A flag --build faz build e publica em um único passo.

Publicando em um repositório privado

Adicione um repositório privado:

poetry config repositories.private https://private.pypi.example.com/simple/
poetry config http-basic.private username password

Publique nele:

poetry publish --repository private

Gerenciamento de versão

Aumente versões usando semantic versioning:

poetry version patch    # 1.0.0 -> 1.0.1
poetry version minor    # 1.0.0 -> 1.1.0
poetry version major    # 1.0.0 -> 2.0.0
poetry version prepatch # 1.0.0 -> 1.0.1a0

Exiba a versão atual:

poetry version

Migrando de requirements.txt

Se você tem um projeto existente usando requirements.txt, a migração para o Poetry é direta.

Etapa 1: Inicializar o Poetry

cd your-project
poetry init --no-interaction

Etapa 2: Adicionar dependências do requirements.txt

Para um arquivo requirements simples:

cat requirements.txt | xargs poetry add

Para arquivos com restrições de versão, adicione pacotes manualmente ou use um script de migração:

import subprocess
 
with open("requirements.txt") as f:
    packages = []
    for line in f:
        line = line.strip()
        if line and not line.startswith("#") and not line.startswith("-"):
            packages.append(line)
 
if packages:
    subprocess.run(["poetry", "add"] + packages)

Etapa 3: Adicionar dependências de desenvolvimento

Se você tiver um requirements-dev.txt:

cat requirements-dev.txt | xargs poetry add --group dev

Etapa 4: Verificar e gerar lock

poetry install
poetry lock --check

Etapa 5: Limpeza

Depois de verificar que tudo funciona, você pode remover os arquivos antigos:

rm requirements.txt requirements-dev.txt setup.py setup.cfg

Exportando de volta para requirements.txt

Se você precisar de um requirements.txt por compatibilidade (builds com Docker, sistemas legados de CI):

poetry export -f requirements.txt --output requirements.txt

Incluir dependências de desenvolvimento:

poetry export -f requirements.txt --with dev --output requirements-dev.txt

Poetry vs pip vs pipenv vs uv: comparação

Escolher a ferramenta certa de gerenciamento de dependências depende dos requisitos do seu projeto. Aqui vai uma comparação detalhada:

Quando escolher cada ferramenta

Escolha Poetry quando você precisa de uma solução completa de empacotamento — gerenciamento de dependências, build e publicação no PyPI em uma única ferramenta, com ecossistema maduro e documentação extensa.

Escolha pip para scripts simples, prototipação rápida, ou quando estiver preso a restrições que exigem as ferramentas padrão. O pip continua sendo a base sobre a qual outras ferramentas se apoiam.

Escolha pipenv para aplicações web em que você precisa de ambientes reprodutíveis, mas não publica pacotes no PyPI. O formato Pipfile separa dependências de desenvolvimento e produção de forma clara.

Escolha uv quando a velocidade de instalação é prioridade, ou quando você quer uma ferramenta única que também gerencia versões do Python. O uv é escrito em Rust e resolve dependências muito mais rápido do que ferramentas baseadas em Python. Ele é compatível com pip e pode atuar como substituto drop-in.

Configuração do Poetry e dicas

Opções úteis de configuração

# Store virtual environments in the project directory
poetry config virtualenvs.in-project true
 
# Use a specific Python version for new environments
poetry config virtualenvs.prefer-active-python true
 
# Disable automatic virtual environment creation
poetry config virtualenvs.create false
 
# View all configuration
poetry config --list

Poetry com Docker

Um Dockerfile de produção usando Poetry:

FROM python:3.12-slim
 
ENV POETRY_VERSION=1.8.0 \
    POETRY_HOME="/opt/poetry" \
    POETRY_VIRTUALENVS_CREATE=false \
    POETRY_NO_INTERACTION=1
 
RUN pip install poetry==$POETRY_VERSION
 
WORKDIR /app
 
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
 
COPY . .
RUN poetry install --without dev
 
CMD ["python", "-m", "my_project"]

Pontos-chave:

• POETRY_VIRTUALENVS_CREATE=false evita a criação de ambiente virtual dentro do container (o próprio container já fornece isolamento).
• Instale dependências antes de copiar o código-fonte para aproveitar o cache de layers do Docker.
• Rode poetry install duas vezes: primeiro sem o projeto (apenas dependências), depois com o projeto.

Poetry com CI/CD

Exemplo com GitHub Actions:

name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install Poetry
        run: pip install poetry
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest
      - name: Run linting
        run: poetry run ruff check .

Poetry em workflows com Jupyter

Cientistas de dados frequentemente trabalham em notebooks Jupyter, onde o gerenciamento de dependências é especialmente importante. O Poetry se integra bem com o Jupyter ao garantir que os notebooks usem o ambiente correto.

Instale o Jupyter dentro do seu projeto Poetry:

poetry add --group dev jupyter ipykernel

Registre o ambiente do Poetry como um kernel do Jupyter:

poetry run python -m ipykernel install --user --name=my-project

Inicie o Jupyter dentro do ambiente do Poetry:

poetry run jupyter notebook

Para uma experiência de Jupyter mais enxuta, com gerenciamento automático de dependências e assistência baseada em IA, o RunCell (opens in a new tab) oferece um ambiente integrado no qual você pode focar na análise em vez da configuração do ambiente. O RunCell lida automaticamente com instalação de pacotes e gerenciamento de kernels, o que complementa o controle de dependências por projeto do Poetry.

Referência de comandos comuns do Poetry

Solucionando problemas comuns

Falhas de resolução de dependências

Problema: o Poetry não consegue encontrar um conjunto compatível de versões.

SolverProblemError: ...unable to find compatible versions...

Solução: afrouxe as restrições de versão ou verifique requisitos conflitantes:

# Show what conflicts exist
poetry show --tree
 
# Try with a wider constraint
poetry add "problematic-package>=1.0"

Resolução lenta

Problema: poetry lock leva muito tempo.

Solução: o Poetry faz cache de metadados de pacotes, mas a primeira resolução em um projeto com muitas dependências pode ser lenta. Se a resolução passar de vários minutos:

# Clear the cache and retry
poetry cache clear --all pypi
 
# Use verbose output to see what is happening
poetry lock -vvv

Ambiente virtual não detectado pela IDE

Problema: VS Code ou PyCharm não encontra o ambiente do Poetry.

Solução: configure ambientes virtuais dentro do projeto:

poetry config virtualenvs.in-project true
poetry install  # Recreates .venv in project root

Depois selecione .venv/bin/python como interpretador na sua IDE.

Erros de hash mismatch

Problema: poetry install reporta hash mismatches.

Solução: regenere o lock file:

poetry lock --no-update

Isso regenera hashes sem alterar as versões de dependências.

FAQ

Para que serve o Python Poetry?

Python Poetry é uma ferramenta de gerenciamento de dependências e empacotamento que lida com instalação de pacotes, resolução de conflitos de versão, gerenciamento de ambientes virtuais e publicação de pacotes no PyPI. Ela substitui a combinação de pip, venv, setuptools e twine por uma ferramenta única e unificada centrada no arquivo de configuração pyproject.toml.

Poetry é melhor que pip?

Poetry e pip servem a propósitos diferentes. O Poetry oferece resolução de dependências, lock files, gerenciamento de ambientes virtuais e publicação de pacotes em uma única ferramenta. O pip é mais simples e funciona bem para instalações diretas. Para projetos que exigem builds reprodutíveis, colaboração em equipe ou publicação de pacotes, o Poetry oferece vantagens significativas. Para scripts rápidos ou projetos simples, o pip continua sendo suficiente.

Como eu mudo de pip para Poetry?

Inicialize o Poetry no seu projeto com poetry init e então adicione suas dependências a partir do requirements.txt usando cat requirements.txt | xargs poetry add. O Poetry cria um arquivo pyproject.toml e um poetry.lock. Depois de verificar que tudo funciona com poetry install, você pode remover o arquivo requirements.txt antigo. Use poetry export se você ainda precisar de requirements.txt por compatibilidade.

O Poetry substitui virtualenv?

Sim. O Poetry cria e gerencia automaticamente ambientes virtuais para cada projeto. Você não precisa criar ou ativar ambientes manualmente. O Poetry armazena ambientes em um cache centralizado por padrão, ou no diretório do projeto se configurado com poetry config virtualenvs.in-project true. Você ainda pode usar poetry shell para ativar o ambiente interativamente.

O Poetry consegue gerenciar múltiplas versões do Python?

O Poetry em si não instala versões do Python, mas funciona com quaisquer versões de Python disponíveis no seu sistema. Use pyenv ou uv para instalar múltiplas versões do Python e então diga ao Poetry qual usar com poetry env use python3.11. O Poetry cria ambientes virtuais separados para diferentes versões do Python dentro do mesmo projeto.

Qual é a diferença entre poetry.lock e requirements.txt?

Um arquivo poetry.lock registra cada pacote instalado e sua versão exata, incluindo todas as dependências transitivas, além de hashes de conteúdo para verificação. Um requirements.txt gerado por pip freeze também lista versões exatas, mas não tem verificação por hash nem rastreamento das relações de dependência. O lock file garante instalações determinísticas em todos os ambientes, enquanto requirements.txt pode produzir resultados diferentes quando dependências transitivas são atualizadas.

Conclusão

O Python Poetry transforma o gerenciamento de dependências de uma fonte de atrito em um workflow mais enxuto. Ao combinar resolução de dependências, gerenciamento de ambiente virtual e publicação de pacotes em uma única ferramenta, ele elimina a toolchain fragmentada que há muito tempo frustra desenvolvedores Python. O arquivo pyproject.toml fornece uma fonte única de verdade, o lock file garante instalações reprodutíveis e o resolvedor de dependências captura conflitos antes que eles causem falhas em runtime.

Seja para construir uma library para o PyPI, gerenciar uma aplicação complexa com dezenas de dependências, ou colaborar com uma equipe que precisa de ambientes consistentes, o Poetry fornece a estrutura e a confiabilidade que o pip sozinho não oferece. A curva de aprendizado é modesta — a maioria dos desenvolvedores se torna produtiva em menos de uma hora — e o tempo economizado com debug de dependências se paga dentro da primeira semana.

Comece rodando poetry new no seu próximo projeto, ou poetry init em um projeto existente. Adicione suas dependências, faça commit do lock file e experimente um gerenciamento de dependências que funciona como deveria. Para workflows de ciência de dados no Jupyter, combine o controle de dependências por projeto do Poetry com o RunCell (opens in a new tab) para um ambiente que lida tanto com gerenciamento de pacotes quanto com análise interativa de forma integrada.