# Migrate a Pipenv Project to uv and Keep the Locked Versions

Yes. An agent converts Pipfile and Pipfile.lock to pyproject.toml and uv.lock with the same pinned versions, repairs what the converter misses, and opens a PR.

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

## What the agent does

The agent reads every file that knows about Pipenv, since the `Pipfile` is rarely the only one. In an API like ExpDev07/coronavirus-tracker-api the `Pipfile` lists fifteen packages and fourteen dev packages, nearly all as `"*"`, with `python_version = "3.8"` and a `[scripts]` table of six commands. `Pipfile.lock` holds the real versions. Around them sit `requirements.txt` and `requirements-dev.txt` generated by `pipenv lock -r`, a `Dockerfile` that installs from `requirements.txt`, `runtime.txt` with `python-3.8.13`, a `tasks.py` whose `generate_reqs` task shells out to Pipenv, a test in `tests/test_cli.py` that does the same, and a `.travis.yml` that runs `pipenv install --dev --skip-lock`. It records a baseline before converting: on Python 3.8 with the pinned requirements, 73 tests pass and 4 fail.

It runs `uvx migrate-to-uv`, and the first attempt aborts. A `Pipfile` has no project name, the tool writes `name = ""` into `[project]`, and `uv lock` rejects the empty name. The tool restores the files and exits. The agent adds a `[project]` table with a name to the existing `pyproject.toml`, which until now held only tool configuration, and runs it again. This time `Pipfile` and `Pipfile.lock` are removed, dependencies move to `[project]` and a `dev` dependency group, and `uv.lock` is written using the old lockfile as constraints. The agent then compares the two lockfiles package by package instead of trusting the success message. Every version carried over. Three packages are gone because their markers apply only below Python 3.8, and a few arrive because a uv lock covers every platform.

The converted project does not install yet, and the reason is the Python version. The tool turns `python_version = "3.8"` into `requires-python = "~=3.8"`, which uv warns it will read as `>=3.8, <4`. On a machine whose default interpreter is 3.11, `uv sync` picks that interpreter and fails compiling `pyyaml` 5.4.1 from source, a 2021 pin with no wheel for it. The agent narrows the range to `>=3.8,<3.9`, writes `.python-version`, and locks again; uv then downloads CPython 3.8 itself and the install succeeds. It says plainly that this keeps the project on an end-of-life Python and that lifting the pins is a different task.

Then it repairs what the converter does not touch. The six `[scripts]` entries have no counterpart in `pyproject.toml` and are dropped without a message, so the agent moves them into the existing `Makefile` and `tasks.py` as `uv run` commands. It regenerates `requirements.txt` with `uv export --no-dev --no-hashes --no-emit-project`, because the `Dockerfile` still installs from that file, and diffs the pins against the old one. It rewrites `generate_reqs` and the test that calls `pipenv lock -r`. That test was one of the four baseline failures for a reason unrelated to this change: a current Pipenv rejects the flag with `No such option: -r`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this project from Pipenv to uv without changing any locked version. First find every file that mentions pipenv, Pipfile or the generated requirements files (CI, Dockerfiles, Makefile, task runners, tests, README, runtime.txt, Procfile) and list them. Create a baseline: build an environment on the Python version the Pipfile requires from the committed lock or requirements files, run the test suite, and record the totals and the names of any failing tests. Run uvx migrate-to-uv. If it aborts, read the error, fix the cause in pyproject.toml and run it again; do not pass --ignore-locked-versions. Compare Pipfile.lock with uv.lock package by package and report every version that differs, every package that disappeared and every package that is new, with the reason. Run uv sync on a machine default interpreter and then on the required Python; if the default one fails, constrain requires-python and add .python-version so uv picks the right interpreter by itself. Carry over anything the converter dropped, including the Pipfile [scripts] table. Regenerate any requirements file other tooling reads with uv export and diff its pins against the old file. Replace Pipenv commands in CI, Makefile, task runner, tests and README with uv equivalents. Run the tests again with uv run and show that the same tests pass and fail as in the baseline; do not fix unrelated failing tests, list them. Do not upgrade Python or any dependency. Open a pull request with the output of every command.",
  "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 `Pipfile` and `Pipfile.lock`, adds `uv.lock` and `.python-version`, and extends `pyproject.toml` with `[project]`, `[dependency-groups]` and `[tool.uv]`. It also touches the files that called Pipenv: the CI file, `Makefile`, `tasks.py`, the test that regenerates requirements, the two requirements files and the README's setup section. The description opens with the list of files found in the search, so a reviewer can see that nothing that mentions Pipenv was left behind.

The lockfile comparison comes next: how many packages kept their version, which were dropped and under which marker, and which are new. For this kind of project the new entries are platform-specific packages such as `colorama` and the build tool `setuptools`, and the description says so, since unexplained additions to a lockfile are what reviewers distrust most. The same comparison is shown for the regenerated `requirements.txt`.

The test summaries close the description: baseline and after, with failing tests named in both. A reviewer checks that the two lists match, that `requires-python` is no wider than what the pins can install on, and that CI now installs from the lockfile. The old CI command used `--skip-lock`, so it never tested the versions that were deployed; the description points that out as a change in behaviour, not only in tooling.

## Run it on every repository still on Pipenv

Each repository is migrated once, when a developer decides to. Send the body to `POST /o/{org}/sessions` from a terminal or an MCP client, with a `request_id` that is a UUID made for this job so a retried request returns the same run. If the agent ends its turn on a question, for instance whether to keep generating `requirements.txt` or switch the Dockerfile to `uv sync`, reply with `POST /o/{org}/sessions/{id}/messages`. The sandbox wakes with the environments it already built.

An organisation with many services scripts it: one request per repository, each with a `request_id` that is a UUID v5 of the repository's full name. The key runs a limited number at once and queues the rest in order. A `webhook_url` set on the key receives `run.completed` or `run.failed` for each run the key started, which is enough to build a checklist of which services have a pull request waiting.

## Why run it on Rush?

The risky part of a package manager migration is silent drift: a lockfile that resolves again and lands on different versions, or an interpreter that changes because the new tool reads the constraint differently. Catching that takes two real environments and a comparison. The agent builds both in its own sandbox, on the exact Python the project names, and the transcript at `GET /o/{org}/sessions/{id}/messages` holds the output of each install and test run. The pull request's statement that nothing moved can be checked against it.

Old projects also fail in ways that depend on the machine. The compile error from an unpinned interpreter appears on a fresh host and not on a laptop that has had Python 3.8 installed for years. A sandbox is that fresh host. The run meets the failure a new contributor or a rebuilt CI image would meet, fixes the cause in the repository, and leaves the evidence attached.

## Frequently asked questions

### Does migrate-to-uv keep the versions from Pipfile.lock?

Yes, by default it passes the old lockfile to `uv lock` as constraints, then locks once more without them. On the fixture this page was written against, every package present in both files kept its version. The agent verifies that with a package-by-package comparison and reports any exception with its cause.

### What happens to the [scripts] section of my Pipfile?

It is not converted. `pyproject.toml` has `[project.scripts]`, but that declares entry points of an installed package, which is a different thing from Pipenv's shell aliases. The agent moves each alias to wherever the repository already keeps commands, a Makefile or a task runner, and rewrites it as `uv run`.

### Why did the first run of the converter fail?

A project table needs a name and a Pipfile does not have one. The tool writes an empty string, uv refuses to parse it, and the migration is rolled back. Adding `[project]` with a `name` to `pyproject.toml` before running the tool resolves it; existing fields in that table are kept.

### Do I still need requirements.txt afterwards?

Only if something reads it. A Dockerfile that runs `pip install -r requirements.txt`, or a platform that detects Python apps by that file, will keep needing it. `uv export` writes it from `uv.lock`, and the agent keeps a command for regenerating it. Where nothing reads the file, the agent proposes deleting it and says what it checked.

### Will this upgrade my dependencies?

No. The request forbids it, and the lockfile comparison is the proof. Pins that are years old stay years old, including ones that only install on an old Python. Raising them is worth doing, as its own pull request with its own test run, once the tooling change has merged.

## The same job on other stacks

- [Migrate a Poetry Project to uv Without Changing Locked Versions](https://getrush.ai/run/migrate-to-uv/poetry/)
- [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/)
- [Migrate a Flask Project to uv](https://getrush.ai/run/migrate-to-uv/flask/)

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