All jobs

Migrate a Python Library From pip to uv

Yes. An agent folds a requirements file into pyproject dependency groups, adds a uv lockfile, moves the Makefile, tox and CI to uv and proves the tests still pass.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent starts by finding every place the project installs itself, because a library's tooling is usually spread across more files than its pyproject.toml. In a library like psf/requests, pyproject.toml already uses the setuptools.build_meta backend with requires-python = ">=3.10", four runtime dependencies, a version read dynamically from requests.__version__, optional extras socks and use_chardet_on_py3, and two PEP 735 [dependency-groups]: test with pytest-httpbin==2.1.0, httpbin~=0.10.0, pytest-cov, pytest-mock, pytest-xdist, pytest>=3 and trustme, and typecheck with pyright and its stubs. Beside it, requirements-dev.txt still lists -e .[socks], pytest>=2.8.0,<10, pytest-cov, the same httpbin pins, trustme and wheel, which is almost the test group but not quite: no pytest-mock, no pytest-xdist, a different pytest range. The Makefile installs it with python -m pip install -r requirements-dev.txt, tox.ini reads it through deps = -rrequirements-dev.txt, and MANIFEST.in ships it in the sdist. No uv.lock exists, and .gitignore already ignores .venv/ and .python-version.

Then it reads the workflows, which is where the migration has to hold. .github/workflows/run-tests.yml runs a matrix of CPython 3.10 through 3.15-dev, the free-threaded 3.14t and pypy-3.11 on Ubuntu 22.04, macOS and Windows, with actions/setup-python caching pip and allow-prereleases: true, then make and make ci; two more jobs uninstall charset_normalizer and chardet, or install urllib3<2, and run the suite again. typecheck.yml installs pip==26.0.1 and runs pip install -e . --group typecheck before pyright, so the project has already started using groups in CI. lint.yml runs pre-commit, publish.yml builds with build==1.4.0 and publishes with trusted publishing and attestations, every action is pinned to a commit SHA with a version comment and persist-credentials: false, and zizmor.yml checks the workflows themselves. dependabot.yml covers github-actions and pre-commit, not pip.

The agent makes the groups the single source of truth. It reconciles requirements-dev.txt into the test group, keeping the stricter pytest range and dropping wheel, which only mattered for legacy installs, and deletes the file along with its lines in MANIFEST.in and the Makefile; tox.ini gets dependency_groups = test in place of the deps line. It runs uv lock, which builds the project's metadata to resolve the dynamic version, and commits uv.lock. make init becomes uv sync --locked --group test and make ci becomes uv run pytest tests --junitxml=report.xml, so the targets the workflows call keep their names. In run-tests.yml it keeps actions/setup-python, because that is what provides 3.15-dev, 3.14t and PyPy on every runner, adds astral-sh/setup-uv pinned to a commit SHA with a version comment the way the file pins everything else, and points uv at the matrix interpreter so the lockfile resolves against each one; the no_chardet and urllib3 jobs become uv pip uninstall and uv pip install "urllib3<2" inside the synced environment. typecheck.yml becomes uv sync --locked --group typecheck and uv run pyright src/requests/. publish.yml is left alone: it builds with build and publishes with trusted publishing, and uv has nothing to add there.

Before it opens the pull request, the agent proves the environment is the same. It runs the suite twice in the sandbox, once from a fresh pip install -r requirements-dev.txt and once from uv sync --locked --group test, and compares pip freeze from both for the packages the tests import; it runs uv run pyright src/requests/ and pre-commit run --all-files, since ruff-check and ruff-format would flag a stray file; and it runs zizmor on the changed workflow, because the repository runs it on every pull request and a new unpinned action would fail there. It writes nothing to docs/, where Read the Docs installs with pip from docs/requirements.txt, and notes that choice in the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate this Python library's development tooling from pip to uv without changing its build backend or its published package. Read pyproject.toml, requirements-dev.txt, Makefile, tox.ini, MANIFEST.in, .gitignore and every workflow under .github/workflows first, and list each place the project installs itself. Reconcile requirements-dev.txt into the existing [dependency-groups] test group, keeping the stricter version ranges where they differ, then delete the file and remove it from MANIFEST.in and the Makefile; change tox.ini to use dependency_groups instead of the deps line. Run uv lock and commit uv.lock. Change the Makefile so init runs uv sync --locked --group test and ci runs uv run pytest tests --junitxml=report.xml, keeping the target names. In the test workflow keep actions/setup-python for the interpreter matrix, add astral-sh/setup-uv pinned to a full commit SHA with a version comment and persist-credentials unchanged, and make uv use the matrix interpreter; convert the no-chardet and urllib3 jobs to uv pip commands inside the synced environment. Convert the type-check workflow to uv sync --locked --group typecheck and uv run pyright. Leave the publish workflow, docs/ and the Read the Docs configuration unchanged. Verify in the sandbox: run the test suite from a pip install of the old requirements file and from uv sync, compare the installed versions of every package the tests import, run pyright, run pre-commit on all files, and run zizmor on the workflows you changed. Open a pull request that lists each file changed and why, pastes the version comparison, and quotes the commands you ran with their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that adds uv.lock, removes requirements-dev.txt, and edits pyproject.toml, Makefile, tox.ini, MANIFEST.in, run-tests.yml and typecheck.yml. Its body lists each file with the reason, pastes the side-by-side versions of the packages the tests import under the old and new install, and quotes the pytest, pyright, pre-commit and zizmor commands with their output. publish.yml, lint.yml, .readthedocs.yaml and everything under src/ and docs/ are untouched.

The repository's own workflows run on the branch and are the real check: the test matrix on three operating systems and eight interpreters now installs through uv, the type-check job syncs the typecheck group, the pre-commit job runs as before, and zizmor reads the new setup-uv step. A matrix entry that uv cannot resolve against, such as a pre-release interpreter, would fail on that one row and name it.

A reviewer reads the version comparison first, since a silent upgrade of urllib3 or pytest is the risk in this migration, then checks that uv.lock resolved against the lowest supported Python and that the no_chardet and urllib3 jobs still exercise what they exercised. Whether a library should commit a lockfile at all is a maintainer's call, and the pull request says so rather than deciding it.

Run it on every Python repository still on pip

A team moving its Python projects to uv starts one run per repository: POST /o/{org}/sessions with this prompt as input and that repository in resources, with a request_id per repository so a retried request returns the run it already started. Each run reads its own files, so a project that has already moved its dependencies into groups gets a workflow change, and one still on a bare requirements file gets the full migration.

Up to the key's max_concurrent runs proceed at once, each in its own sandbox with its own interpreters. A webhook_url on the key receives run.completed or run.failed with data.session_url when each turn ends, so a script can collect the pull requests as they arrive. Once a turn has finished, a follow-up on POST /o/{org}/sessions/{id}/messages wakes the same sandbox, for instance to ask it to keep a requirements export for a platform that needs one.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The risk in a uv migration is not writing the lockfile, it is proving that nothing else moved: the same package versions, the same make targets, the same matrix of interpreters in CI. That proof takes a clean machine, two fresh installs and a run of the full suite under each, and a laptop with the project's old virtualenv already activated hides exactly the mistakes you want to catch. In a Rush sandbox the agent starts from nothing, installs both ways, and the transcript keeps the comparison.

Workflows that pin every action to a commit and run zizmor on themselves were written carefully. The agent follows those rules from the files rather than from habit, and the pull request shows a reviewer the commands and the diff of installed versions, not a promise that it should work.

Frequently asked questions

Will it upgrade my dependencies?

No. The runtime dependencies in pyproject.toml are untouched and the lockfile resolves within the ranges already declared. Where the old requirements file and the test group disagreed, the agent keeps the stricter range and pastes the before-and-after versions of every test dependency in the pull request so you can see any difference.

Why keep actions/setup-python in the matrix?

Because the matrix includes a pre-release CPython, the free-threaded build and PyPy on three operating systems, and setup-python with allow-prereleases is what provides them today. uv then installs into that interpreter. Replacing the interpreter source as well would be a second change with its own risks, and the pull request says that it was left out on purpose.

Should a library commit uv.lock at all?

The lockfile only affects contributors and CI; the published wheel carries the ranges from pyproject.toml. Committing it makes CI reproducible, at the cost of a periodic uv lock --upgrade. The agent commits it and states the trade-off in the pull request; dropping it is one file to delete if the maintainers prefer.

What happens to tox?

tox.ini keeps its environments and now installs the test group through dependency_groups, which tox supports natively, instead of reading a requirements file that no longer exists. Contributors who prefer tox keep working the same way.

Does it touch the documentation build?

No. .readthedocs.yaml installs the package and docs/requirements.txt with pip on Read the Docs, where uv is not part of the picture. The agent leaves that path alone and says so.

More Python jobs

The same job on other stacks

Keep reading