# 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 Rush](https://cloud.getrush.ai/run/migrate-to-uv/python/). Opens 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`

```json
{
  "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.

## 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

- [Review Pull Requests on a Python Library](https://getrush.ai/run/review-pull-requests/python/)
- [Write Property-Based Tests for a Python Library](https://getrush.ai/run/write-property-tests/python/)
- [Add Bandit Security Checks to a Python Project's CI](https://getrush.ai/run/add-bandit-to-ci/python/)

## The same job on other stacks

- [Migrate a Slack Bolt for Python App From pip to uv](https://getrush.ai/run/migrate-to-uv/slack-bolt/)
- [Migrate a Textual App From Poetry to uv](https://getrush.ai/run/migrate-to-uv/textual/)
- [Migrate a Django REST Framework Project to uv](https://getrush.ai/run/migrate-to-uv/django-rest-framework/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
