# Migrate a Django REST Framework Project to uv

Yes. An agent moves your DRF project to pyproject.toml and uv.lock, updates both Dockerfiles and the workflow, runs the tests with uv run and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-to-uv/django-rest-framework/). 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 installs Python before it changes one. In a project shaped like HackSoftware/Django-Styleguide-Example, dependencies are split across `requirements/base.txt`, which pins `Django==5.2.7`, `djangorestframework==3.16.1`, `psycopg2==2.9.11`, `celery==5.5.3`, `django-celery-results`, `django-celery-beat`, `whitenoise`, `django-filter`, `django-cors-headers`, `django-structlog[celery]`, `drf-jwt`, `boto3`, `gunicorn`, `sentry-sdk`, the Google auth client and `pyotp`, and `requirements/local.txt`, which includes it and adds `pytest`, `pytest-django`, `factory-boy`, `Faker`, `ipdb`, `ipython`, `django-debug-toolbar`, `mypy` with `django-stubs` and `djangorestframework-stubs`, `ruff` and `pre-commit`. A root `requirements.txt` holds one line, `-r requirements/base.txt`, because the README says Heroku needs a root-level file; `runtime.txt` says `python-3.12.4`; and `pyproject.toml` holds only `[tool.ruff]` with a line length of 120 and `target-version = "py312"`.

From that it writes a `[project]` table into the existing `pyproject.toml` with the `base.txt` packages as `dependencies` at the same pins, so the migration changes the tool and not the libraries, and the `local.txt` extras as a `dev` dependency group. `requires-python` follows `runtime.txt`, and a `.python-version` of `3.12.4` makes `uv` and the images agree. `uv lock` resolves the rest; the agent compares the locked transitive versions with what `pip` would have installed and lists in the pull request any package that moved. The `[tool.ruff]` section stays where it is, and the agent notes that `.pre-commit-config.yaml` pins `ruff-pre-commit` at `v0.13.1` while `local.txt` pins `ruff==0.14.0`, a mismatch the migration makes visible but does not resolve.

Then the places that call `pip`. `docker/local.Dockerfile` starts `FROM python:3.12.4`, adds `requirements/` and runs `pip install -r requirements/local.txt`; `docker/production.Dockerfile` does the same with `base.txt`. The agent copies the `uv` binary into each image, copies `pyproject.toml` and `uv.lock` before the application so the dependency layer caches, runs `uv sync --locked` in the local image and `uv sync --locked --no-dev` in the production one, and puts `.venv/bin` on `PATH`, so the `docker-compose.yml` commands (`python manage.py runserver`, the `celery` worker and `beat` entries) and the `docker/*_entrypoint.sh` scripts that call `gunicorn` and `celery` keep working unchanged. `.github/workflows/django.yml` has two jobs: `docker_build`, which runs `ruff`, `mypy` and `py.test` through `docker compose run`, and `build`, which installs with `pip install -r requirements/local.txt` under two pip caches keyed on the requirements files. The agent replaces the pip steps with `astral-sh/setup-uv`, `uv sync --locked`, and `uv run` in front of `ruff check .`, `mypy --config mypy.ini styleguide_example/` and `pytest`, and drops the two cache steps the lockfile makes unnecessary. The `Procfile` and the root `requirements.txt` stay for Heroku, with the latter generated by `uv export --format requirements.txt` from the lock with the dev group left out, and the pull request says how to regenerate it.

Last, it proves it in the sandbox. `pytest.ini` points at `config.django.test` and `config/django/base.py` reads `DATABASE_URL` with a Postgres default, so the agent starts the `db` service from `docker-compose.yml`, runs `uv lock`, `uv sync`, `uv run ruff check .`, `uv run mypy --config mypy.ini styleguide_example/` and `uv run pytest`, builds both images with `docker compose build`, and pastes each output. `requirements/` is removed only after all of that passes and nothing else reads it.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this Django REST Framework project from pip requirements files to uv and open a pull request. Read requirements.txt, requirements/base.txt, requirements/local.txt, runtime.txt, pyproject.toml, pytest.ini, mypy.ini, .pre-commit-config.yaml, Procfile, docker-compose.yml, docker/local.Dockerfile, docker/production.Dockerfile, the docker entrypoint scripts and .github/workflows/django.yml first. Add a [project] table to pyproject.toml with the base.txt packages as dependencies at their current pins and the local.txt extras as a dev dependency group, set requires-python from runtime.txt, add .python-version, run uv lock and list any transitive package whose version differs from a pip install of the old files. Update both Dockerfiles to copy uv, install with uv sync --locked in a cached layer (--no-dev in production) and put .venv/bin on PATH so docker-compose.yml and the entrypoint scripts stay unchanged. Replace the pip steps in both workflow jobs with setup-uv, uv sync --locked and uv run, and remove the pip caches. Keep the Procfile and regenerate the root requirements.txt with uv export without the dev group for Heroku. Start the Postgres service, run uv run ruff check ., uv run mypy, uv run pytest and docker compose build, and paste the output in the pull request. Remove requirements/ only if nothing still reads it.",
  "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 with a `[project]` table and a `dev` group in `pyproject.toml`, a new `uv.lock` and `.python-version`, both Dockerfiles installing with `uv sync --locked`, the workflow's two jobs on `uv`, a regenerated root `requirements.txt` for Heroku and the `requirements/` directory removed. The description lists the packages in each group, every transitive version that changed, and the output of `ruff`, `mypy`, `pytest` and `docker compose build` from the sandbox.

The workflow runs on the pull request, so the first run of the `uv` steps is the change that adds them, and both jobs have to pass with the lock before anyone merges. The `docker_build` job in particular builds the local image, which is where a missing `PATH` entry or a dependency left out of the `dev` group would show.

A reviewer checks that nothing the app needs at runtime landed in the `dev` group, that the production image installs with `--no-dev`, that `uv.lock` is copied before the application so the layer caches, and that the Heroku `requirements.txt` was generated from the lock rather than written by hand. Then they merge and rebuild.

## Run it on every Django repository still on pip

A team moving all its Django services to `uv` sends one `POST /o/{org}/sessions` per repository with this prompt and the repository in `resources`, with a `request_id` per repository so a retried request returns the run already started. Each run reads its own requirements layout, so a project with one flat file gets one group and a project split like this one gets two, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` or `run.failed` when each turn ends, with `session_url` to read the pull request from, so a script can collect them as they arrive.

## Why run it on Rush?

A packaging migration is wide rather than deep: two requirements files, two Dockerfiles, a compose file, three entrypoint scripts, a two-job workflow and a Heroku file all have to agree afterwards. In a Rush sandbox the agent changes them together, starts Postgres and runs the lint, the type check, the tests and both image builds for real, and every command and its output is kept in the run's record.

The pull request is reviewable because it separates what changed from what did not: the libraries keep their pins, the compose commands keep their shape, and the only versions that move are the transitive ones the lock resolved, which are listed. The same request works unchanged on the next Django service.

## Frequently asked questions

### Do the library versions change?

The direct dependencies keep the exact pins from `base.txt` and `local.txt`. Only transitive packages, which the old files never pinned, are resolved by `uv lock`, and the pull request lists each one whose version differs from a pip install of the old files.

### What about Heroku and the root requirements.txt?

The README says Heroku needs a root-level `requirements.txt`, so the file stays, generated from `uv.lock` with `uv export --format requirements.txt` and the dev group left out. The pull request records the command so it can be regenerated after the next `uv lock`.

### Does docker-compose.yml change?

No. The images put `.venv/bin` on `PATH`, so `python manage.py runserver`, the `celery` worker and `beat` commands, and the entrypoint scripts that call `gunicorn` resolve to the environment `uv sync` created without any edit to the compose file.

### How do the tests run in the sandbox?

`config/django/base.py` reads `DATABASE_URL` with a Postgres default, so the agent starts the `db` service from `docker-compose.yml` and runs `uv run pytest` against it with the `config.django.test` settings from `pytest.ini`. The workflow's `build` job does the same with its own `postgres` service.

## More Django REST Framework jobs

- [Find the Test Coverage Gaps in a Django REST Framework API](https://getrush.ai/run/test-coverage-gaps/django-rest-framework/)
- [Upgrade a Django REST Framework API to Python 3.13](https://getrush.ai/run/upgrade-python-version/django-rest-framework/)
- [Write API Tests for a Django REST Framework API](https://getrush.ai/run/write-api-tests/django-rest-framework/)

## The same job on other stacks

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

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