# Migrate a Textual App From Poetry to uv

Yes. An agent rewrites a Textual app's pyproject from Poetry tables to PEP 621, locks with uv at the same versions, proves the tl command still runs, and opens a PR.

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

## What the agent does

The agent reads how the project is built and installed before it changes a table, because a Poetry project's metadata, scripts and build backend all move at once. In an app laid out like Textualize/toolong, `pyproject.toml` has only Poetry tables: `[tool.poetry]` with the name `toolong`, version `1.5.0`, an MIT license, the README and three repository URLs; `[tool.poetry.dependencies]` with `python = "^3.8"`, `click = "^8.1.7"`, `textual = "^0.58.0"` and `typing-extensions = "^4.9.0"`; a `dev` group with `textual-dev = "^1.4.0"`; `[tool.poetry.scripts]` mapping `tl` to `toolong.cli:run`; and a `poetry-core` build backend. `poetry.lock` was written by Poetry 1.8.2 at lock version 2.0 and resolves 21 packages, among them `textual` 0.58.0 and `textual-dev` 1.5.1. The code sits in `src/toolong/`, and `cli.py` reads its own version with `importlib.metadata.version("toolong")` for `--version`, which only works when the package is installed. `README.md` tells users to `pipx install toolong` or `pip install toolong`. There is no test suite, no Makefile and no CI workflow, so the proof has to come from installing and running the tool.

The translation is mechanical but the version ranges need care. Poetry's caret means something different on a `0.x` version: `^0.58.0` is `>=0.58.0,<0.59.0`, while `^8.1.7` is `>=8.1.7,<9`. The agent writes a `[project]` table with `requires-python = ">=3.8,<4.0"`, `dependencies` as `click>=8.1.7,<9`, `textual>=0.58.0,<0.59.0` and `typing-extensions>=4.9.0,<5`, so the migration keeps the same resolution and does not smuggle in a Textual upgrade; the pull request says that `textual` is pinned to a release line far behind the current one and that widening it is a separate change. `[project.scripts]` gets `tl = "toolong.cli:run"`, `[project.urls]` the three links, `[dependency-groups]` a `dev` group with `textual-dev>=1.4.0,<2`, and `license` the SPDX string `MIT`. The build backend becomes `uv_build`, whose default module path is `src/<name>`, which is what the repository already has; the agent runs `uv build` to confirm the backend finds `src/toolong` and leaves a note that `hatchling` is the alternative if the team prefers one build backend across projects.

`uv lock` writes `uv.lock`, and the agent compares it with the old lock before deleting that file: `uv export --no-hashes` against the package list in `poetry.lock`, which should show the same 21 names at the same versions on the sandbox's platform, with any difference called out by name. `poetry.lock` is removed, `[tool.poetry]` is gone, and `.gitignore` gains nothing because it already ignores `build/` and `dist/`. The README's install section keeps `pipx` and `pip` and adds `uv tool install toolong`, and a short contributor paragraph names `uv sync` and `uv run tl`. The agent also writes a `.python-version` of `3.12` for contributors, since `requires-python` still allows 3.8 for users but no maintainer should develop on a release that old.

Then it proves the result the way a user would. `uv sync` creates the environment with the `dev` group, `uv run tl --version` prints `1.5.0` through `importlib.metadata`, so the editable install registered the package, `uv run tl --help` shows the `--merge` and `--output-merge` options from `cli.py`, and `uv run python -c "import textual; print(textual.__version__)"` prints `0.58.0`. `uv build` produces the sdist and wheel under `dist/`, and `uvx --from dist/toolong-1.5.0-py3-none-any.whl tl --version` runs the built wheel in a fresh environment, which is the same path a `pipx` or `uv tool` user takes. Because `tl` is a full-screen terminal app, the agent does not try to drive its UI; it pipes a small log file through `tl` in non-TTY mode, which `cli.py` handles by reading stdin, and keeps the output.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this Textual application from Poetry to uv. Read pyproject.toml, poetry.lock, src/toolong/cli.py, README.md and .gitignore first. Replace the tool.poetry tables with a PEP 621 project table that keeps the same name, version, license, readme, urls and script, translate each caret range exactly as Poetry reads it including the 0.x case for textual, move the dev group to dependency-groups, and switch the build backend to uv_build. Run uv lock, compare the resolved packages and versions with poetry.lock and report any difference, then delete poetry.lock. Add a .python-version for contributors, and update the README install and contributing sections for uv without removing pipx or pip. Run uv sync, uv run tl --version, uv run tl --help, uv build, and run the built wheel with uvx, then pipe a small log file through tl in non-TTY mode. Open a pull request that shows each command's output and says that the Textual version range was kept rather than widened.",
  "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 rewrites `pyproject.toml`, adds `uv.lock` and `.python-version`, deletes `poetry.lock` and changes `README.md`. The description shows the `[project]` table beside the old `[tool.poetry]` one, the package-by-package comparison of the two locks, and the output of `uv run tl --version`, `uv build` and the `uvx` run of the wheel, so a reviewer can see the version string, the script entry point and the build backend all survived.

There is no workflow in this repository, so no check runs on the pull request; the run's record is the evidence, and it keeps `uv lock`, the export comparison and every run of `tl` in order. The pull request suggests a `uv sync` and `uv build` workflow as a follow-up and names the `add-github-actions-ci` job for it.

Before merging, a reviewer decides whether to widen the `textual` range now that the lock is under their control, whether `requires-python` should drop 3.8, and whether to keep `uv_build` or standardise on `hatchling`. The agent changes nothing under `src`.

## Run it on every Python repository still on Poetry

A team with several Textual or Click tools on Poetry starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `pyproject.toml`, so a project with `[tool.poetry.extras]` gets `[project.optional-dependencies]`, one with a `packages` include list outside `src` gets `hatchling` with the matching configuration instead of `uv_build`, and one already on PEP 621 tables gets only the lock swapped.

After that, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request changes pyproject.toml dependencies, check that uv.lock changed with it and that no tool.poetry table came back, and say so in a comment" keeps the lock honest. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

## Why run it on Rush?

A Poetry-to-uv migration done by hand goes wrong in the places a diff does not show: a `^0.58.0` turned into `>=0.58.0` that silently upgrades Textual across many breaking releases, a script entry that no longer resolves so `tl` is gone after install, or a build backend that cannot find a `src` layout and ships an empty wheel. The agent locks, builds and runs the real tool in its sandbox, compares the two locks package by package and runs the built wheel in a clean environment before it opens the pull request.

Every command stays with the run, from `uv lock` to the `uvx` run of the wheel, and the pull request quotes them. The same migration over a dozen Python tools at once costs no more attention than one, because each run has its own machine, its own record and its own pull request.

## Frequently asked questions

### Will my dependency versions change?

Not by this pull request. Each Poetry caret is translated to the range Poetry itself reads, including the `0.x` case where `^0.58.0` stops at `0.59.0`, and `uv lock` is compared against `poetry.lock` so the resolution comes out the same. Widening `textual` is called out as a separate decision, because it crosses many releases with breaking changes.

### Why uv_build and not hatchling or setuptools?

The repository already uses a `src/toolong` layout, which is exactly what `uv_build` expects with no configuration, so the switch adds no table. `hatchling` is the choice when a team wants one backend for projects that do not follow that layout, and the pull request says where its two lines would go. `poetry-core` could stay as the backend too, but keeping it means keeping Poetry metadata that PEP 621 now carries.

### Does pipx install still work for users?

Yes. The wheel is a normal wheel with the `tl` entry point in its metadata, which `pipx`, `pip` and `uv tool install` all read the same way. The agent proves it by running the built wheel with `uvx --from`, which installs it into a fresh environment the way `pipx` does.

### How is a terminal app tested without a terminal?

The agent does not drive the full-screen UI. It checks the entry point with `--version` and `--help`, and uses the non-TTY branch in `cli.py` that reads a log from standard input, piping a small file through it. Textual's own `App.run_test` harness is how a team would add real UI tests later, and the pull request names it.

## More Textual jobs

- [Upgrade a Textual App to the Current Textual Release](https://getrush.ai/run/upgrade-textual/textual/)
- [Write Pytest Tests for a Textual Terminal App](https://getrush.ai/run/write-pytest-tests/textual/)
- [Write Snapshot Tests for a Textual App](https://getrush.ai/run/write-snapshot-tests/textual/)

## The same job on other stacks

- [Migrate a Django REST Framework Project to uv](https://getrush.ai/run/migrate-to-uv/django-rest-framework/)
- [Migrate a Flask Project to uv](https://getrush.ai/run/migrate-to-uv/flask/)
- [Migrate a Pipenv Project to uv and Keep the Locked Versions](https://getrush.ai/run/migrate-to-uv/pipenv/)

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