poetry

name	poetry
description	Manage Python dependencies, lock files, and project environments using Poetry.
license	MIT
compatibility	claude cursor opencode
metadata	{"version":"1.0.0","languages":"python","audience":"developers","workflow":"automation","since":"2026-02-25"}

What I do

I handle the full Poetry dependency-management lifecycle:

• Add or remove packages — update pyproject.toml and poetry.lock in one step
• Sync the environment — install exactly what the lock file specifies
• Regenerate the lock file — after you edit pyproject.toml, safely re-resolve without unintended upgrades
• Run commands in the project environment — no manual venv activation needed
• Initialise a new project — scaffold a new Poetry-managed project or migrate from pip/requirements.txt

When to use me

• Use this skill when the project is Poetry-managed (for example, poetry.lock exists, or the team standard is Poetry).
• You want to add, update, or remove a dependency
• You pulled a branch and need the environment to match the updated lock file
• You edited pyproject.toml directly and need the lock file regenerated
• You want to run a script, test suite, or tool inside the project's virtual environment
• You are starting a new Python project with Poetry, or migrating from pip/requirements.txt

Use Instead [if available]

• Use uv when the project is uv-managed (for example, uv.lock is the lockfile of record).
• Use ci-fix when your primary goal is diagnosing/remediating a failing CI run instead of general dependency work.

Example usage

/poetry add requests
/poetry add --dev pytest
/poetry remove httpx
/poetry install
/poetry lock
/poetry run pytest
/poetry init

---

Workflow

Adding and removing dependencies

Add a runtime dependency (goes into [tool.poetry.dependencies] in pyproject.toml):

poetry add <package>           # e.g. poetry add requests
poetry add "<package>>=2.0"    # with version constraint

Add a dev dependency (goes into [tool.poetry.group.dev.dependencies] — Poetry 1.2+ group syntax):

poetry add --group dev <package>    # e.g. poetry add --group dev pytest ruff

Dev dependencies are installed in the development environment only and excluded from production installs (poetry install --no-dev or poetry install --without dev). Use --group dev for test runners, linters, and formatters.

Remove a dependency:

poetry remove <package>        # removes from pyproject.toml and updates poetry.lock
poetry remove --group dev <package>    # remove a dev dependency

After every add or remove, Poetry automatically:

1. Updates pyproject.toml
2. Resolves all constraints and regenerates poetry.lock
3. Installs or uninstalls the package in the active virtual environment

Version resolution summary: Poetry prints the resolved version and any transitive changes. If a conflict is detected, it reports the conflicting constraints — fix the version bounds in pyproject.toml and retry.

---

Syncing the environment

poetry install installs exactly what poetry.lock specifies — no more, no less. It is the canonical way to bring an environment into alignment with the lock file.

poetry install

When to use it:

• After git pull when teammates updated poetry.lock
• After checking out a branch with different lock file state
• After cloning a repository for the first time
• After manually editing pyproject.toml followed by poetry lock

Already in sync: If the environment already matches the lock file, poetry install exits cleanly. It is safe to run on every git pull.

Dev vs production install:

poetry install --without dev    # skip dev dependency groups (production-like)
poetry install --only dev       # install only dev dependencies

---

Regenerating the lock file

Use poetry lock after editing pyproject.toml directly — for example, changing a version constraint, adding a dependency entry by hand, or removing one.

Version-aware safe regeneration:

Poetry version	Safe command	Notes
2.x (current)	poetry lock	Safe by default — existing resolved versions preserved; --no-update flag removed
1.x (legacy)	poetry lock --no-update	Required to prevent upgrading all deps; plain poetry lock in 1.x upgrades everything

Check your Poetry version: poetry --version

Detect which command to use:

# Poetry 2.x — safe by default:
poetry lock

# Poetry 1.x — must pass --no-update for safe regen:
poetry lock --no-update

If --no-update is not recognised (Poetry 2.x), use plain poetry lock.

Upgrade all dependencies to latest compatible versions:

# Poetry 2.x:
poetry update --lock          # regenerate lock with all deps upgraded (no env install)
# or:
poetry lock --regenerate      # full re-resolution from scratch

# Poetry 1.x:
poetry update                 # upgrades and installs

Upgrade a single package:

poetry update <package>       # upgrade one package (both versions)

When to use each variant:

Scenario	Poetry 2.x	Poetry 1.x
Edited constraint in pyproject.toml	poetry lock	poetry lock --no-update
Removed a dependency	poetry lock	poetry lock --no-update
Upgrade one package	poetry update <pkg>	poetry update <pkg>
Periodic refresh of all deps	poetry update --lock	poetry update

After regenerating the lock file, run poetry install to apply the changes to your environment.

Critical: The skill will never run a command that silently upgrades unrelated packages. Always use the safe-default command for your Poetry version.

---

Running commands in the project environment

poetry run executes any command inside the project's virtual environment — without manual activation.

poetry run <command>

Examples:

poetry run pytest                      # run tests
poetry run pytest tests/unit/ -v      # with arguments
poetry run python src/main.py         # run a script
poetry run ruff check .               # run a tool
poetry run python -m mypackage        # module invocation

Replaces manual venv activation: Use poetry run <cmd> instead of:

source $(poetry env info --path)/bin/activate

poetry run works consistently across platforms and CI environments without shell state side-effects.

Tip: To open a shell inside the venv: poetry shell (Poetry 1.x) or poetry run bash (Poetry 2.x removed poetry shell in favour of explicit activation).

---

Initialising a new project

Scaffold a new Poetry project (creates a directory with pyproject.toml and src layout):

poetry new my-project

Initialise in an existing directory (interactive pyproject.toml wizard):

poetry init

This prompts for project name, version, description, Python version constraint, and initial dependencies.

Set Python version:

poetry env use python3.12     # pin to a specific Python for this project

Poetry stores the selected Python in the virtualenv metadata.

Migrate from requirements.txt:

1. Run poetry init if no pyproject.toml exists
2. Add runtime dependencies:

   # Add each dependency from requirements.txt:
   poetry add requests click flask
   # Or read from file:
   cat requirements.txt | xargs poetry add
   

3. Add dev dependencies:

   poetry add --group dev pytest ruff mypy
   

4. Verify the generated poetry.lock is correct: poetry install
5. Delete requirements.txt once migration is verified

---

Tips for Success

1. Always use poetry run instead of venv activation — it works in CI without any setup steps and eliminates the risk of running commands in the wrong environment.

2. poetry lock is safe by default in Poetry 2.x — but in Poetry 1.x you must use poetry lock --no-update to avoid upgrading unrelated packages. Check poetry --version if you're unsure.

3. Always review the lock diff after poetry update — poetry update can pull in breaking changes. Check git diff poetry.lock before committing and run your test suite.

4. Use --group dev for test and lint tools — keeping pytest, ruff, mypy, and similar tools in the dev group ensures they are never installed in production (poetry install --without dev).

5. Run poetry install after every git pull — or make it the first step in your dev environment setup script. This ensures your environment always matches the committed lock file.

6. Check Poetry is installed: poetry --version. Install with curl -sSL https://install.python-poetry.org | python3 - or brew install poetry.

7. Commit poetry.lock to version control — the lock file is the source of truth for reproducible environments. Never add it to .gitignore.