1. 📘 Guia Completo do Poetry¶

1.1. Introdução¶

O Poetry é uma ferramenta de gerenciamento de dependências e empacotamento para projetos Python. Ele facilita a criação de ambientes virtuais, o controle de versões e a publicação de pacotes.

1.2. Instalação e Configuração¶

1.2.1. Instalação via pip¶

pip install poetry

1.2.2. Listar Configurações¶

poetry config --list

Saída esperada:

cache-dir = "/path/to/cache/directory"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = true
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

1.2.3. Criar ambientes virtuais no diretório do projeto¶

poetry config virtualenvs.in-project true

1.2.4. Especificar o Caminho do Python¶

Exemplo de caminho:

Python padrão: C:\Python39\python.exe
Anaconda: C:\Users\username\Anaconda3\python.exe

poetry env use C:\Users\SeuUsuario\anaconda3\python.exe

1.2.5. Verificar Informações do Ambiente¶

poetry env info

Saída típica:

Virtualenv
Python:         3.11.7
Implementation: CPython
Path:           ...\.venv
Executable:     ...\.venv\Scripts\python.exe
Valid:          True

1.2.6. Verificação de Criação do `.venv`¶

poetry show

1.3. Uso do Poetry¶

1.3.1. Iniciar um Novo Projeto¶

poetry new meu_projeto
poetry add nome_do_pacote
poetry install
poetry lock
poetry show

1.3.2. Usar em Projeto Existente¶

poetry init

1.3.3. Usar em Projeto Clonado¶

Clone o repositório.
Verifique se há pyproject.toml.
Execute:

poetry install

1.3.4. Executar Scripts com Poetry¶

Dentro do ambiente:

poetry shell
python script.py

Fora do ambiente:

poetry run python script.py

1.4. Comandos Essenciais do Poetry¶

1.4.1. Instalação de Dependências¶

poetry install
poetry add pacote
poetry add pacote --dev
poetry remove pacote

1.4.2. Build e Publicação¶

poetry build
poetry publish
poetry publish --dry-run

1.4.3. Ambiente Virtual¶

poetry shell
poetry run comando
poetry env list
poetry env remove python-versao

1.4.4. Diagnóstico e Informação¶

poetry show
poetry show pacote
poetry check
poetry debug info

1.4.5. Configurações¶

poetry config --list
poetry config repositories.<nome> <url>
poetry config http-basic.<nome> <usuario> <senha>

2. Warning¶

2.1. Mudanças no Comando `poetry shell` (a partir da versão 2.0)¶

Desde a versão 2.0.0, o comando poetry shell não é mais instalado por padrão. Em vez disso, o Poetry recomenda utilizar o novo comando env activate, ou, se necessário, instalar o plugin correspondente.

2.1.1. ✅ Forma Recomendada: Ativando o Ambiente Virtual¶

poetry env activate

Ativa o ambiente virtual gerenciado pelo Poetry.
Nota: esse comando não é um substituto direto do antigo poetry shell, mas é a forma moderna recomendada.

2.1.2. 🔄 Restaurar o Comando Antigo (`shell`)¶

poetry self add poetry-plugin-shell

Isso instala o plugin que reabilita o comando shell como antigamente.

2.1.3. ▶️ Executar Scripts sem Entrar no Ambiente¶

poetry run python seu_script.py

Executa comandos ou scripts Python diretamente no ambiente virtual gerenciado pelo Poetry, sem ativá-lo manualmente.

2.1.4. ℹ️ Explicação Técnica¶

O comando poetry shell foi removido do core para tornar o Poetry mais modular.
O novo método env activate é mais flexível e explícito, e segue uma abordagem alinhada com práticas modernas.
A instalação de plugins via poetry self add é agora o caminho padrão para restaurar funcionalidades opcionais.

📚 Documentação oficial:
🔗 https://python-poetry.org/docs/managing-environments/#activating-the-environment