What the agent does
Moving from Poetry to uv is advertised as one command, and the agent runs that command first to see how far it gets. Before that it finds every place Poetry is used. In a project like Donnype/fastapi-template there are four. pyproject.toml has a [tool.poetry] table, six caret-pinned dependencies, a dev group marked optional = true, and poetry-core as the build backend. poetry.lock pins 42 packages. api/Dockerfile installs poetry==1.4.2 with pip, sets two POETRY_ variables, copies the lockfile and runs poetry install, then poetry install --with dev in its test stage. And README.md tells contributors to run poetry install and poetry run. The Makefile and the workflow only call Docker Compose, so they do not change.
The one command, uvx migrate-to-uv, stops with Could not lock dependencies, aborting the migration. The tool passes every locked version to uv as a constraint, and this lockfile holds three packages at two versions each, split by Python version: typing-extensions, filelock and platformdirs. uv is asked for typing-extensions 4.15.0 and 4.16.0 at once and finds no solution. The tool offers --ignore-locked-versions, and the agent measures what that would cost before taking it: a fresh uv lock moves 31 of the 42 packages, among them pydantic from 2.9.2 to 2.14.3 and starlette from 0.40.0 to 0.46.2. That is a dependency upgrade hidden inside a tooling change. So it converts with --skip-lock, adds the 39 single-version pins as constraint-dependencies for one uv lock, and removes them again. The resulting uv.lock matches the old lock on every package except the three that were split, and a second uv lock leaves it unchanged.
The converted pyproject.toml has a second problem. The tool swaps the build backend for uv_build, and uv sync then fails with Expected a Python module at: src/fastapi_template/__init__.py. This repository is an application whose code is in api/, not a package to install, so the agent removes the [build-system] table and the sync succeeds. A third difference is silent. Poetry installed the dev group only with --with dev; uv installs a group named dev by default. A plain uv sync therefore puts pytest and pre-commit into the environment, and the image's runtime stage needs uv sync --locked --no-dev to stay as lean as it was.
Then the Dockerfile. Until it is changed, the build fails at the COPY line on "/poetry.lock" not found. The agent replaces the pip install of Poetry with a COPY --from of a pinned uv image, drops the POETRY_ variables, copies uv.lock, and uses the two sync commands. The sandbox has no Docker, so it installs docker.io and starts dockerd first. The Compose plugin the Makefile calls is not in that package, so the agent builds each stage with docker build --target and runs the test image's pytest against a PostgreSQL it installs with apt. The runtime image has uvicorn and alembic on its path and no pytest; the test image passes all five tests on the locked versions.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this repository from Poetry to uv without changing any locked dependency version. First list every place Poetry is used: pyproject.toml tables, poetry.lock, Dockerfiles, Makefile, CI workflows, pre-commit config, scripts and README. Record the number of packages in poetry.lock and any package locked at more than one version. Run uvx migrate-to-uv. If it cannot lock, do not accept re-resolved versions: convert without locking, then produce uv.lock with the old lock's versions as temporary constraints, remove the constraints, and confirm a second uv lock changes nothing. Report every package whose version differs from poetry.lock and why. Check the build-system table the tool wrote: if this project is an application and not an installable package, remove it; otherwise make sure the backend can find the package, and prove it with uv sync. Compare how dependency groups install: a group that was optional under Poetry must not be installed in a production image, so use --no-dev there or set default-groups. Update every Dockerfile to install a pinned uv, copy uv.lock, and sync with --locked; keep the virtual environment where PATH already expects it. Docker may not be available here: install docker.io and start dockerd, and since the compose plugin may be missing, build each stage with docker build --target. If tests need PostgreSQL, install it with apt and run the test image against it. Confirm the runtime image has no test tools and the test image passes the suite. Update the README commands. Delete poetry.lock. Open a pull request with the version comparison, the problems found in the generated config, and the build and test output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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
A pull request that deletes poetry.lock, adds uv.lock, rewrites the project metadata in pyproject.toml into the standard [project] and [dependency-groups] tables, rewrites the Poetry lines of api/Dockerfile and the two Poetry commands in the README. Tool settings in pyproject.toml for pytest, Black, Vulture and Ruff are untouched.
The description starts with a version table: packages in the old lock, packages in the new one, and each package whose version differs. For a project like the one above that is three rows, the three packages Poetry had locked twice, and the reviewer can see that everything the application imports is at the version it was. Under it are the two defects in the generated config and how each was resolved, then the output of both image builds and the test run inside the test image.
Before merging, a reviewer checks the two sync commands in the Dockerfile, since swapping them would ship test tools to production, and decides one thing the agent leaves open: whether to accept newer versions now that the tooling has changed. That is a separate pull request, and with uv it is a single uv lock --upgrade whose diff is easy to read.
Run it on every repository still on Poetry
A package manager is switched once per repository, by someone who has decided to. A developer sends this body to POST /o/{org}/sessions from a terminal or an MCP client with a request_id that is a UUID made for the job, and keeps working. The pull request is on the session when the run completes, and a follow-up to POST /o/{org}/sessions/{id}/messages wakes the same sandbox if a reviewer wants something done differently, with both images still built.
A team standardising on uv sends the body once per repository from a script, each with a request_id that is a UUID v5 of the repository's full name. A key runs a limited number of sessions at once and queues the others, and its webhook_url receives run.completed for each run it started. The version tables that come back show at a glance which migrations were clean and which lockfiles had splits that needed handling.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The risk in this migration is not the tool; it is a lockfile that changes underneath a pull request titled as tooling. Guarding against that means parsing both lockfiles and comparing them package by package, then building the images to see whether the result still runs. In its own sandbox the agent does both, with Docker and a database installed for the purpose, and each command with its output is in the transcript at GET /o/{org}/sessions/{id}/messages.
It is also work with three or four traps that each cost an hour the first time: the aborted migration, the build backend, the default group, the stale COPY line. The agent hits them in sequence in one run, without a developer waiting between attempts, and the pull request lists each one with the error it produced.
Frequently asked questions
Why does migrate-to-uv fail with "Could not lock dependencies"?
It turns each version in poetry.lock into a constraint and asks uv to lock against them. When Poetry locked one package at two versions for different Python versions, those two constraints contradict each other. The fix is to migrate with --skip-lock and constrain only the packages that have a single locked version.
Will my dependency versions change?
They will if you let uv resolve from scratch, and they should not if the migration is done carefully. In Donnype/fastapi-template a fresh resolve moves 31 of 42 packages. With the old versions passed as constraints, only the three packages Poetry had locked twice end up different.
Do I still need a [build-system] table?
Only if the project is a package that gets built or installed. For an application that is run from its source tree, uv needs no build backend, and one that expects a src/ layout will make uv sync fail.
How do optional Poetry groups map to uv?
Poetry groups become [dependency-groups]. The difference is the default: uv installs the group named dev unless told otherwise, where an optional Poetry group was installed only on request. Use uv sync --no-dev where the group must stay out, or set default-groups in [tool.uv].
More Poetry jobs
The same job on other stacks
- Migrate a Python Library From pip to uv (Python)
- Migrate a Slack Bolt for Python App From pip to uv (Slack Bolt)
- Migrate a Textual App From Poetry to uv (Textual)
- Migrate a Django REST Framework Project to uv (Django REST Framework)