All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

Keep reading