migrate-pip-to-uv（将 pip 迁移到 uv）

Migrate pip/pip-tools Monorepo to uv

A skill for automating the migration of a Python monorepo project from pip/pip-tools workflows (requirements files, pip-compile, etc) to uv's project workflow (pyproject.toml, uv.lock, universal resolution).

Purpose

• Convert requirements files (requirements.in, requirements.txt, requirements-dev.in, requirements-dev.txt, etc) to pyproject.toml and uv.lock
• Migrate development, docs, and platform-specific dependency groups
• Ensure universal, locked dependencies for all platforms
• Update project workflows to use uv commands and environments

Workflow Steps

1. Analyze Existing Requirements Files

- Detect requirements.in, requirements.txt, requirements-dev.in, requirements-dev.txt, requirements-docs.in, requirements-docs.txt, etc - Identify platform-specific requirements files (e.g. requirements-win.txt, requirements-linux.txt)

1. Initialize uv Project

- Run uv init to create pyproject.toml if not present

1. Import Base Dependencies

- Run uv add -r requirements.in -c requirements.txt to preserve locked versions

1. Import Development Dependencies

- Run uv add --dev -r requirements-dev.in -c requirements-dev.txt - If requirements-dev.in includes -r requirements.in, strip those lines before import

1. Import Docs/Other Groups

- Run uv add -r requirements-docs.in -c requirements-docs.txt --group docs (repeat for other groups)

1. Import Platform-Specific Constraints

- For each platform file, use uv pip compile requirements.in -o requirements-<platform>.txt --python-platform <platform> --no-strip-markers - Add with uv add -r requirements.in -c requirements-win.txt -c requirements-linux.txt...

1. Import Dependency Sources

- For local paths or git dependencies, ensure they are mapped in [tool.uv.sources] in pyproject.toml

1. Sync and Lock

- Run uv lock to generate uv.lock - Run uv sync to create.venv and sync environment

1. Update Project Workflows

- Replace pip/pip-tools commands with uv equivalents (e.g. uv run pytest) - Document new workflow in README.md

Example Usage

migrate-pip-to-uv

Example Migration Commands

• uv init
• uv add -r requirements.in -c requirements.txt
• uv add --dev -r requirements-dev.in -c requirements-dev.txt
• uv add -r requirements-docs.in -c requirements-docs.txt --group docs
• uv pip compile requirements.in -o requirements-win.txt --python-platform windows --no-strip-markers
• uv add -r requirements.in -c requirements-win.txt -c requirements-linux.txt
• uv lock
• uv sync
• uv run pytest

Best Practices

• Use pyproject.toml for all dependency groups
• Use uv.lock for universal, platform-agnostic locking
• Prefer uv run for all commands in the environment
• Document migration steps and new workflow for contributors
• Remove obsolete requirements files after migration

References

• uv migration guide
• uv concepts: projects
• uv universal resolution
• uv dependency sources