# Migrate a Poetry Project to uv Without Changing Locked Versions

Yes. The agent converts pyproject.toml, carries the locked versions into uv.lock, fixes what the migration tool gets wrong, and rebuilds the Docker image.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-to-uv/poetry/). Opens the console with this prompt ready to send, in a Project that has your repository.

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

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

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

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.

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

- [Add Dependabot to a Poetry Project](https://getrush.ai/run/add-dependabot/poetry/)
- [Fix 'The option "--no-dev" does not exist' After pip install poetry Picks Up Poetry 2](https://getrush.ai/run/fix-poetry-no-dev-option-does-not-exist/poetry/)

## The same job on other stacks

- [Migrate a Python Library From pip to uv](https://getrush.ai/run/migrate-to-uv/python/)
- [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/)
