Poetry / Rye Dependency Management Skill

Overview

Poetry and Rye are Python dependency managers that enforce lockfile-driven, deterministic builds. Both use pyproject.toml as the single configuration file. Poetry is the established standard (since 2018); Rye is a newer Astral tool that bridges to uv. For greenfield projects, consider modern-python skill (uv-native). This skill covers Poetry/Rye for existing codebases and teams already invested in these tools.

When to Use

• When maintaining existing Poetry or Rye projects

• When a team has standardized on Poetry and migration to uv is not planned

• When publishing Python packages to PyPI (Poetry has mature publishing support)

• When managing monorepo Python workspaces

• When auditing or upgrading dependency lockfiles

Iron Laws

• ALWAYS commit the lockfile (poetry.lock or requirements.lock ) -- without it, builds are non-deterministic and CI/CD will resolve different versions than development.

• NEVER use pip install in a Poetry/Rye-managed project -- it bypasses the resolver and creates ghost dependencies invisible to the lockfile.

• ALWAYS use poetry add /rye add to add dependencies -- manual pyproject.toml edits without re-locking create stale lockfiles.

• NEVER pin transitive dependencies manually -- let the solver manage the full dependency graph; pinning transitive deps causes resolver conflicts.

• ALWAYS separate runtime and development dependencies into groups -- shipping dev/test dependencies in production images wastes space and expands attack surface.

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Editing pyproject.toml deps without running poetry lock

Lockfile becomes stale; CI installs different versions than intended Always run poetry lock or rye lock after any dependency change

Using poetry install without --no-root in CI Installs the project in editable mode unnecessarily; slower CI builds Use poetry install --no-root for library deps only, --only main for production

Committing .venv/ directory to version control Bloats repo; virtualenvs are platform-specific and non-portable Add .venv/ to .gitignore ; recreate with poetry install or rye sync

Mixing pip and Poetry in the same project Creates two dependency graphs; pip-installed packages invisible to Poetry Use only poetry add /rye add for all dependency changes

Using * version constraints for all dependencies No upper bound protection; major version bumps break silently Use compatible release (^ in Poetry) or upper-bounded ranges

Workflow

Poetry Project Setup

Initialize new project

poetry init --name my-project --python ">=3.12"

Add dependencies by group

poetry add requests httpx poetry add --group dev ruff pytest pytest-cov poetry add --group docs sphinx

Install all groups

poetry install

Install production only

poetry install --only main

Rye Project Setup

Initialize new project

rye init my-project cd my-project

Add dependencies

rye add requests httpx rye add --dev ruff pytest pytest-cov

Sync (install) dependencies

rye sync

pyproject.toml Configuration (Poetry)

[tool.poetry] name = "my-project" version = "0.1.0" description = "Project description" authors = ["Team <team@example.com>"] readme = "README.md"

[tool.poetry.dependencies] python = ">=3.12" requests = "^2.31" httpx = "^0.27"

[tool.poetry.group.dev.dependencies] ruff = "^0.9" pytest = "^8.0" pytest-cov = "^6.0"

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

CI/CD Integration (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: pipx install poetry - name: Cache dependencies uses: actions/cache@v4 with: path: ~/.cache/pypoetry key: poetry-$HASH_OF_LOCKFILE - name: Install dependencies run: poetry install --no-root - name: Lint run: poetry run ruff check . - name: Test run: poetry run pytest --cov

Security Audit

Poetry: audit dependencies for known CVEs

poetry audit

Rye: use pip-audit integration

rye run pip-audit

Migration to uv

When ready to migrate from Poetry/Rye to uv:

Export Poetry dependencies

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

Initialize uv project

uv init uv add $(grep -v '^#' requirements.txt | grep -v '^-' | cut -d'=' -f1)

Verify

uv sync uv run pytest

See modern-python skill for the complete uv workflow.

Complementary Skills

Skill Relationship

modern-python

uv-native workflow (recommended for greenfield projects)

python-backend-expert

Framework-specific patterns (Django, FastAPI, Flask)

tdd

Test-driven development methodology

comprehensive-unit-testing-with-pytest

Testing strategies and patterns

Memory Protocol (MANDATORY)

Before starting:

Read .claude/context/memory/learnings.md for prior Python packaging decisions.

After completing: Record any migration issues, version constraints, or resolver conflicts to .claude/context/memory/learnings.md .

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.