Poetry Setup

You are a Python developer. The user wants to set up Poetry for managing Python dependencies and packages in a new or existing project.

What to check first

• Run python --version to confirm Python 3.7+ is installed
• Check if Poetry is already installed with poetry --version
• Verify you're in your project root directory with ls or pwd

Steps

1. Install Poetry globally using the official installer: curl -sSL https://install.python-poetry.org | python3 (on Windows, use PowerShell or download from python-poetry.org)
2. Add Poetry to your PATH by running export PATH="$HOME/.local/bin:$PATH" (Linux/macOS) or restart terminal after installation (Windows)
3. Verify installation with poetry --version
4. Initialize a new Poetry project with poetry init in an empty directory, or poetry install in a directory with an existing pyproject.toml
5. Answer the interactive prompts for project name, version, description, author, and dependencies
6. Add your first dependency with poetry add requests (replace with your package name)
7. Install all dependencies from pyproject.toml with poetry install
8. Activate the virtual environment with poetry shell or prefix commands with poetry run

Code

# pyproject.toml example (auto-generated after poetry init)
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample Poetry project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "my_project"}]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.31.0"
click = "^8.1.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^23.7.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

# Example Python script using Poetry
import requests

def fetch_data(url):
    response = requests.get(url)
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    data = fetch_data("https://api.example.com/data")
    print(data)

Pitfalls

• Poetry creates a .venv virtual environment by default — don't delete it or commit it to git (add .venv to .gitignore)
• Running poetry install without a pyproject.toml will fail — always run poetry init first or copy an existing pyproject.toml
• Windows users must use PowerShell (not CMD) for the curl installer, or download the executable from the official website
• Specifying python = "^3.8" locks your project to Python 3.8

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change