# Migrate a Python Project from flake8 to Ruff

Yes. An agent maps your flake8 plugins, isort and pyupgrade settings onto Ruff rules, swaps the pre-commit hooks, fixes what the new linter finds and opens a PR.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how linting is wired today before it touches a config file. In a library like tqdm/tqdm, `.pre-commit-config.yaml` runs flake8 7.3.0 with `-j8` and six plugins (`flake8-broken-line`, `flake8-bugbear`, `flake8-comprehensions`, `flake8-debugger`, `flake8-isort`, `flake8-pyproject`), then `pyupgrade` with `--py38-plus`, then `isort` 9.0.1, beside hooks that must stay: the `pre-commit-hooks` set, `nbstripout`, and local hooks that regenerate `README.rst`, `tqdm/completion.sh` and run a quick `pytest`. `pyproject.toml` holds `[tool.flake8]` with `max_line_length = 99` and an exclude list, `[tool.isort]` with `line_length = 99`, `multi_line_output = 4` and `known_first_party = ["tqdm", "tests"]`, and a `[tool.yapf]` block the agent leaves alone because formatting is not the job. The `Makefile` has a `flake8` target that runs `pre-commit run -a flake8` and `nbstripout`, and the `pre-commit.ci` block sets `autoupdate_schedule: monthly`.

It writes a `[tool.ruff]` section with `line-length = 99`, `target-version = "py38"` to match `requires-python = ">=3.8"`, and the flake8 exclude list as `extend-exclude`. Under `[tool.ruff.lint]` it selects the rule families that stand in for each plugin: `E`, `F` and `W` for pycodestyle and pyflakes, `B` for bugbear, `C4` for comprehensions, `T10` for debugger, `I` for isort and `UP` for pyupgrade. `flake8-broken-line` has no Ruff equivalent, so its single rule is named in the pull request as dropped rather than silently lost. `[tool.ruff.lint.isort]` gets `known-first-party = ["tqdm", "tests"]`; isort's `multi_line_output = 4` has no exact counterpart, so the agent runs `ruff check --select I --diff` first and shows which import blocks would be rewrapped before deciding whether to accept that diff or keep the old wrapping with a per-file ignore.

Then it runs `ruff check .` and reads every finding against what flake8 accepted. Rules in the new families that flake8 never ran, such as `UP` modernisations beyond what `pyupgrade --py38-plus` already applied, are either fixed with `ruff check --fix` when the fix is safe or added to `ignore` with a comment saying why. The handful of `# noqa` comments in `tqdm/std.py`, `tqdm/utils.py`, `tqdm/asyncio.py` and `tqdm/notebook.py` carry codes like `F401`, `BLE001` and `B042`; the agent checks each against Ruff's rule list, keeps the ones Ruff knows and removes codes it does not, so `RUF100` stays clean if a maintainer enables it later.

Finally it replaces the flake8, isort and pyupgrade entries in `.pre-commit-config.yaml` with the `ruff-pre-commit` hook running `ruff` with `--fix`, keeps every other hook in place, renames the `Makefile` target, deletes `[tool.flake8]` and `[tool.isort]` from `pyproject.toml`, and runs `pre-commit run -a` and `pytest -k "not slow"` in the sandbox so the quick-test hook that `pre-commit` already defines still passes with coverage above its `--cov-fail-under=70` floor.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Replace flake8, isort and pyupgrade with Ruff in this Python project. Read .pre-commit-config.yaml, pyproject.toml and the Makefile first and list every flake8 plugin and setting in use. Add a [tool.ruff] configuration that keeps the same line length, target Python version and excludes, select the Ruff rule families that cover each plugin, and name any plugin that has no Ruff equivalent in the pull request instead of dropping it quietly. Carry over the isort first-party setting. Run ruff check and fix or explicitly ignore each new finding, keeping existing noqa comments only where Ruff knows the code. Swap the pre-commit hooks for ruff-pre-commit, keep every other hook, update the Makefile lint target, remove the old flake8 and isort config, then run pre-commit on all files and the quick test suite before opening a pull request with the rule mapping in its description.",
  "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 changes `pyproject.toml`, `.pre-commit-config.yaml` and the `Makefile`, plus whichever source files `ruff check --fix` touched, mostly import ordering and a few `noqa` codes. Its description is a table: each flake8 plugin on the left, the Ruff rule family that replaces it on the right, and a row for any plugin left behind, so a maintainer sees in one glance that nothing enforced before is quietly unenforced now.

The run's record keeps the `ruff check` output before and after the fixes, the `--diff` preview of import rewrapping, and the full `pre-commit run -a` and `pytest` output, so a reviewer does not need to reproduce the migration locally to trust it.

Before merging, a reviewer checks the dropped-rule row, decides whether the import wrapping diff is acceptable or should be pinned back, and confirms that `pre-commit.ci` will keep autoupdating the new hook on its monthly schedule as it did the old ones.

## Run it on every Python repository in your org

A migration like this is a one-time change per repository, so the natural loop is over repositories, not over time. A script on your side reads `GET /o/{org}/github` for the repositories the Rush GitHub App reaches, filters the ones with a `.pre-commit-config.yaml` that mentions flake8, and sends one `POST /o/{org}/sessions` per repository with this body and that repository in `resources`. A `request_id` that is a UUID v5 of the repository name makes the script safe to rerun: a second request for the same repository returns the run already started instead of opening a second pull request.

Set a webhook URL on the API key and each run reports `run.completed` with its `session_url` when its pull request is up, so one dashboard shows which repositories are migrated, which are waiting on review, and which runs ended with a problem to look at.

## Why run it on Rush?

The hard part of a linter migration is not writing the config, it is proving parity: that every rule the old setup enforced is still enforced, and that the new rules did not sneak in behaviour changes under the name of a fix. That needs the old and new linters run on the same tree, their outputs compared, and the tests run after the automatic fixes. The agent does all three in a sandbox that has the repository's own Python version and pre-commit cache, and the record shows exactly which command produced which finding.

Running it on Rush rather than a laptop also means the same migration can run across every Python repository at once, each in its own sandbox, each ending in its own pull request with its own mapping table, instead of one engineer repeating the exercise repository by repository over a quarter.

## Frequently asked questions

### Does this change code formatting too?

No. The job replaces the linters, not the formatter. In a project like tqdm the `[tool.yapf]` block stays untouched and `ruff format` is not introduced. The only source changes are the ones `ruff check --fix` makes for the selected rules, mostly import order, and each one is visible in the diff.

### What happens to flake8 plugins Ruff does not implement?

They are named in the pull request as dropped, with the rule they enforced. `flake8-broken-line`, for example, has no Ruff counterpart. The agent never pretends a rule carried over, so the decision to live without it or to keep flake8 for that one plugin is yours.

### Will Ruff flag things flake8 never did?

Often, because a rule family like `UP` or `B` in Ruff may cover more codes than the plugin version you ran. The agent handles each new finding one of two ways: a safe automatic fix, or an entry in `ignore` with a one-line reason. Nothing is left as a failing lint in the pull request.

### Does pre-commit.ci keep working?

Yes. The `ci:` block in `.pre-commit-config.yaml` is left as it is, and `ruff-pre-commit` is a normal hook repository with tagged releases, so the monthly `autoupdate` bumps it the same way it bumped flake8 and isort.

### Which Python version does Ruff target?

The one `requires-python` already declares. For tqdm that is `py38`, which keeps `UP` from suggesting syntax the oldest supported interpreter cannot run and matches the `--py38-plus` flag the pyupgrade hook used.

## More Python jobs

- [Migrate a Python Project from setup.py to pyproject.toml](https://getrush.ai/run/migrate-setup-py-to-pyproject/python/)
- [Migrate a Python Package to PyPI Trusted Publishing](https://getrush.ai/run/migrate-to-trusted-publishing/python/)
- [Migrate a Python Library From pip to uv](https://getrush.ai/run/migrate-to-uv/python/)

## The same job on other stacks

- [Replace flake8 and pycodestyle With Ruff Without Reformatting Your Code](https://getrush.ai/run/migrate-flake8-to-ruff/flake8/)

## More jobs like this: Hand off a long task

- [Migrate a Cobra CLI to golangci-lint v2](https://getrush.ai/run/migrate-golangci-lint-v2/cobra/)
- [Replace Grunt With npm Scripts in a Node.js App](https://getrush.ai/run/migrate-grunt-to-npm-scripts/nodejs/)

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