# Python Upgrade

> Safely upgrade Python dependencies using uv. Use when asked to "upgrade dependencies", "update packages", "check for updates", or fix version mismatches in a Python project. Use when this capability is needed.

- Skill: `tomevault-io/python-upgrade` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/python-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/python-upgrade/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/python-upgrade

---


# Safe Python Dependency Upgrade

This skill provides a structured process for safely upgrading Python dependencies using `uv`, ensuring project stability through pre-upgrade health checks and post-upgrade validation.

## 1. Preparation & Health Check

Before making any changes, verify the current state of the project:

1. **Baseline Health Check**:
   - Run the test suite: `make test`.
   - _Constraint_: If the baseline tests fail, resolve those issues before proceeding with upgrades.
2. **Backup**:
   - Backup `uv.lock` and `pyproject.toml`: `cp uv.lock uv.lock.bak` and `cp pyproject.toml pyproject.toml.bak`.

## 2. Upgrade Execution

Choose the appropriate upgrade path based on the user's request. Refer to [../common-references/python-commands.md](../common-references/python-commands.md) for project-specific commands.

### Targeted Upgrade (Recommended)

Use this when the user specifies a package or a small set of packages.

1. **Upgrade**: Run `uv add <package>@latest` or `uv lock --upgrade-package <package>`.
2. **Verify**: Check `pyproject.toml` or `uv.lock` to ensure the version has been updated.

### Full Upgrade (Maintenance)

Use this for general dependency maintenance.

1. **Upgrade**: Run `uv lock --upgrade`.
2. **Check for Changes**: Review the `uv.lock` changes and check for major version bumps.

## 3. Validation & Verification

After the upgrade, ensure the project remains stable:

1. **Re-sync**: Run `uv sync --all-extras` to update the environment.
2. **Invoke Verifier**: Use the `verifier` subagent ([../../agents/verifier.md](../../agents/verifier.md)) to run the full build, lint, and test cycle (e.g., `make lint`, `make test`, `make build`).
3. **Handle Failure**: If any check reports persistent issues it cannot fix, analyze the breaking changes and apply manual fixes or roll back.

## 4. Finalization

1. **Commit**: Create a commit with the updated `pyproject.toml` and `uv.lock`.
   - _Message Suggestion_: `chore(deps): upgrade dependencies`
2. **Cleanup**: Remove backup files: `rm *.bak`.

## Rollback Plan

If validation fails and cannot be easily fixed:

1. **Restore**: `mv pyproject.toml.bak pyproject.toml` and `mv uv.lock.bak uv.lock`.
2. **Re-sync**: Run `uv sync --all-extras` to restore the environment.
3. **Report**: Notify the user of the failure and the reasons (e.g., specific breaking changes).

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/yu-iskw) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->