migrate-to-uv

Migrate to uv

Convert Python projects from Poetry/pipx/pip to uv.

Pre-Migration Assessment

IMPORTANT: Before starting any migration, assess the project for blockers. Read pyproject.toml, setup.py (if present), and the build configuration to check for the following. Report findings to the user before proceeding.

Check 1: C/C++/Rust Extensions

Look for signs of compiled extensions:

• setup.py with ext_modules, cffi, cython, or Extension() calls
• Build dependencies like setuptools, cffi, cython, pybind11, maturin, scikit-build-core
• .c, .cpp, .pyx, or .rs source files referenced in the build

If found: uv_build does NOT support compiling C/C++/Rust extensions. The project must use a compatible build backend (setuptools, scikit-build-core, maturin, or hatchling with extension plugins). This is a non-trivial change — warn the user that the build backend swap may require significant effort and testing, especially for projects with complex setup.py logic.

Check 2: Private Package Indexes

Look for [[tool.poetry.source]] sections or references to private PyPI mirrors.

If found: uv handles authentication differently from Poetry. Poetry uses poetry config http-basic.<name> <user> <pass>, while uv uses environment variables:

• UV_INDEX_<NAME>_USERNAME / UV_INDEX_<NAME>_PASSWORD
• Or UV_INDEX_URL with credentials embedded
• Or keyring integration

The migration tool won't convert auth config. The user needs to set up credentials separately for CI and local dev. See the "Private indexes" section below for format conversion.

Check 3: Monorepo / Multiple pyproject.toml Files

Look for multiple pyproject.toml files, path dependencies between packages, or Poetry monorepo plugins (poetry-plugin-monorepo, monoranger).

If found: This is actually a good candidate for migration — uv workspaces handle monorepos much better than Poetry. But the migration is more involved than a single-package project. See the "Monorepo / Workspace Migration" section below.