--- title: "Poetry para Python: Guia Completo" url: "https://python.dev.br/guias/configurando-poetry/" markdown_url: "https://python.dev.br/guias/configurando-poetry.MD" description: "Aprenda a usar Poetry para gerenciar dependências e ambientes virtuais em Python. Instalação, configuração, comandos e publicação de pacotes" date: "2025-11-28" author: "" --- # 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: ```bash curl -sSL https://install.python-poetry.org | python3 - ``` No Windows (PowerShell): ```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: ```bash poetry --version ``` ### Autocompletar no terminal Para Bash: ```bash poetry completions bash >> ~/.bash_completion ``` Para Zsh: ```bash poetry completions zsh > ~/.zfunc/_poetry ``` ## Criando um novo projeto ```bash 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: ```toml [tool.poetry] name = "meu-projeto" version = "0.1.0" description = "" authors = ["Seu Nome "] 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: ```bash cd projeto-existente poetry init ``` O Poetry faz perguntas interativas para gerar o `pyproject.toml`. ## Gerenciando dependências ### Adicionando dependências ```bash # 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 ```bash poetry remove flask poetry remove --group dev black ``` ### Atualizando dependências ```bash # 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): ```bash poetry install ``` ## Ambientes virtuais O Poetry cria e gerencia ambientes virtuais automaticamente. Para executar comandos dentro do ambiente: ```bash # 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 ```bash # 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`: ```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: ```toml [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): ```bash poetry install --without dev,docs ``` ## Migrando de pip para Poetry Se você já tem um `requirements.txt`: ```bash # 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 ```toml [tool.pytest.ini_options] testpaths = ["tests"] ``` ```bash poetry run pytest ``` ### Black e Ruff ```toml [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: ```bash # 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 ```bash 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. O gerenciamento de dependências evoluiu em todas as linguagens modernas. Compare a abordagem do Poetry com o Go Modules no golang.com.br ou o Cargo do Rust, que são frequentemente citados como referência em gerenciamento de pacotes.