Which package managers are supported?

Supported managers are pip, poetry, and pipenv, detected from manifest files (requirements.txt, pyproject.toml, Pipfile).

How are breaking changes handled?

Automatic breaking-change detection is performed; Critical changes block upgrades, High risks trigger warnings, and Moderate/Low changes are logged.

What outputs are produced after upgrades?

Updated manifests (requirements.txt or pyproject.toml) and a verification/report detailing upgrades and results are generated.

ln-713-pip-upgrader

Scanned

npx machina-cli add skill levnikolaevich/claude-code-skills/ln-713-pip-upgrader --openclaw

Files (1)

SKILL.md

5.2 KB

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

ln-713-pip-upgrader

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader

Upgrades Python dependencies with automatic breaking change detection.

Overview

Aspect	Details
Input	Project path, package manager type
Output	Updated requirements.txt/pyproject.toml
Supports	pip, poetry, pipenv

Workflow

See diagram.html for visual workflow.

Phases: Pre-flight → Detect Manager → Security Audit → Check Outdated → Apply Upgrades → Verify Installation → Report

Phase 0: Pre-flight Checks

Check	Required	Action if Missing
requirements.txt OR pyproject.toml OR Pipfile	Yes	Block upgrade
Virtual environment active	No	Warn user (risk of system pollution)

Workers assume coordinator (ln-710) already verified git state and created backup.

Phase 1: Detect Manager

Manager	Indicator Files
pip	requirements.txt
poetry	pyproject.toml + poetry.lock
pipenv	Pipfile + Pipfile.lock

Phase 2: Security Audit

Commands

Manager	Command
pip	`pip-audit --json`
poetry	`poetry audit` (via plugin)
pipenv	`pipenv check`

Actions

Severity	Action
Critical	Block upgrade, report
High	Warn, continue
Moderate/Low	Log only

Phase 3: Check Outdated

Commands

Manager	Command
pip	`pip list --outdated --format=json`
poetry	`poetry show --outdated`
pipenv	`pipenv update --outdated`

Phase 4: Apply Upgrades

Commands

Manager	Command
pip	`pip install --upgrade <package>`
pip (freeze)	`pip freeze > requirements.txt`
poetry	`poetry update`
pipenv	`pipenv update`

MCP Tools for Migration Search

Priority Order (Fallback Strategy)

Priority	Tool	When to Use
1	mcp__context7__query-docs	First choice for library docs
2	mcp__Ref__ref_search_documentation	Official docs and PyPI
3	WebSearch	Latest info, community solutions

Context7 Usage

Step	Tool	Parameters
1. Find library	mcp__context7__resolve-library-id	libraryName: "pydantic"
2. Query docs	mcp__context7__query-docs	query: "pydantic v1 to v2 migration breaking changes"

MCP Ref Usage

Action	Tool	Query Example
Search	mcp__Ref__ref_search_documentation	"python pydantic 2 migration guide"
Read	mcp__Ref__ref_read_url	URL from search results

WebSearch Fallback

Use when Context7/Ref return no results:

"<package> python <version> breaking changes migration"
"<ImportError message> <package> fix"

Phase 5: Verify Installation

Commands

Check	Command
Import test	`python -c "import <package>"`
Tests	`pytest` or `python -m pytest`

Phase 6: Report Results

Report Schema

Field	Description
project	Project path
packageManager	pip, poetry, or pipenv
duration	Total time
upgrades[]	Applied upgrades
verification	PASSED or FAILED

Common Breaking Changes

MANDATORY READ: Load breaking_changes_patterns.md for full patterns.

Package	Breaking Version	Key Changes
pydantic	1 → 2	V1 compatibility layer needed
sqlalchemy	1 → 2	Query syntax changes
fastapi	0.99 → 0.100+	Pydantic v2 required

Configuration

Options:
  # Upgrade scope
  upgradeType: major          # major | minor | patch

  # Security
  auditLevel: high
  minimumReleaseAge: 14

  # Python specific
  pythonVersion: "3.12"
  useVirtualenv: true

  # Verification
  runTests: true

Error Handling

Error	Cause	Solution
ImportError	Breaking API change	Search Context7/Ref for migration
Dependency conflict	Version mismatch	Try pip-compile or poetry lock

References

Definition of Done

Package manager detected (pip/poetry/pipenv) from indicator files
Security audit completed (pip-audit/poetry audit/pipenv check)
Outdated packages identified and listed
Upgrades applied with requirements.txt/pyproject.toml updated
Breaking changes handled via MCP migration guides
Import tests and pytest pass after upgrades
Report returned with upgrades applied and verification status

Version: 1.1.0 Last Updated: 2026-01-10

Source

git clone https://github.com/levnikolaevich/claude-code-skills/blob/master/ln-713-pip-upgrader/SKILL.mdView on GitHub

Overview

ln-713-pip-upgrader upgrades Python dependencies for pip, poetry, and pipenv with automatic breaking-change detection. It orchestrates pre-flight checks, security audits, and outdated checks, then applies upgrades and updates project manifests (requirements.txt or pyproject.toml) with verification.

How This Skill Works

It runs through a defined workflow: detect the dependency manager from manifest files, perform security audits, fetch outdated packages, apply upgrades, and verify the installation. It updates the appropriate manifest and can generate a report of upgrades and results.

When to Use It

When upgrading Python dependencies in a pip/poetry/pipenv project, with breaking-change handling
During a security-critical upgrade requiring an audit before applying updates
If the project uses requirements.txt or pyproject.toml and needs updates
To ensure automated, verifiable upgrades with post-install verification
When you need a generated upgrade report including duration and upgrades

Quick Start

Step 1: Provide the project path and target package manager (pip/poetry/pipenv)
Step 2: Run ln-713-pip-upgrader to detect the manager, perform pre-flight checks, and apply upgrades
Step 3: Validate installation, run tests, and review the generated report

Best Practices

Run in an isolated virtual environment to prevent system pollution
Ensure a backup or git state is available before upgrades
Review breaking-change patterns (e.g., pydantic 1→2) before applying
Update lockfiles/manifest after upgrades (pip freeze, poetry update, or pipenv update)
Run the project’s test suite and manual validation after upgrades

Example Use Cases

A Django project using requirements.txt upgrades several libs with automatic security-audit checks
A FastAPI app migrating from pydantic 1.x to 2.x with breaking-change handling
A Poetry-managed project updating pyproject.toml and poetry.lock via poetry update
A Pipenv project upgrading dependencies using Pipfile and Pipfile.lock with audit
A project that generates a post-upgrade verification report including duration and upgrades

Frequently Asked Questions

Add this skill to your agents