# Migrate From Flask-RESTPlus to Flask-RESTX

Yes. An agent renames the imports, fixes the settings Flask-RESTX silently ignores, calls every endpoint to prove validation still works, and opens a pull request.

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

## What the agent does

Flask-RESTPlus is no longer maintained, and Flask-RESTX is the fork that kept its API. The import rename is the part everyone expects. The agent starts earlier, by finding out whether the project still installs at all. In an API like postrational/rest_api_demo, `requirements.txt` pins `flask-restplus==0.9.2`, `Flask-SQLAlchemy==2.1` and `Werkzeug==0.16.1`, the last one being the usual workaround for Flask-RESTPlus failing to import on Werkzeug 1.0. On Python 3.11 those pins resolve to Flask 1.1 and Jinja2 2.11 with an unpinned MarkupSafe, and importing the app stops with `ImportError: cannot import name 'soft_unicode' from 'markupsafe'`. So there is no working baseline to compare against, and the agent says so instead of pretending one exists.

It then changes `flask_restplus` to `flask_restx` in the five files that import it (`api/restplus.py`, the two endpoint modules, `serializers.py` and `parsers.py`), replaces the three pins with `flask-restx` and a current `Flask-SQLAlchemy`, and updates `install_requires` in `setup.py` to match. `Api`, `Resource`, `fields`, `reqparse`, `api.model`, `api.inherit`, `@api.expect` and `@api.marshal_with` keep their names, so the app imports and `/api/swagger.json` answers 200. A migration that stops here looks finished.

The repository has no tests, so the agent writes a short script with Flask's test client that creates a category and a post and then calls each route, including the failure cases. Two things show up. Listing posts returns 500, because `posts.py` calls `posts_query.paginate(page, per_page, error_out=False)` in two places and Flask-SQLAlchemy 3 accepts those arguments by keyword only. And a `POST` to `/api/blog/posts/` with no `title` is no longer rejected: `app.py` sets `RESTPLUS_VALIDATE` and `RESTPLUS_MASK_SWAGGER`, Flask-RESTX reads `RESTX_VALIDATE` and `RESTX_MASK_SWAGGER`, and an unknown config key raises nothing. The invalid body reaches `create_blog_post` and fails later with a 404 from the `NoResultFound` handler.

The agent renames both keys, moves `ERROR_404_HELP` to `RESTX_ERROR_404_HELP` (the old name still works but warns), and passes `page=` and `per_page=` by keyword. It reruns the script and checks that the missing-title request now answers 400 with `'title' is a required property`. It leaves the module name `api/restplus.py` and the `RESTPLUS_` names in `settings.py` alone unless asked, since those are the project's own identifiers, and lists them in the pull request as optional cleanup.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this project from Flask-RESTPlus to Flask-RESTX. First try a fresh install of the current pinned requirements on the Python version the project targets and import the app; report whether it still works, with the exact error if not. Then replace flask_restplus imports with flask_restx, replace the flask-restplus pin with flask-restx in every manifest (requirements files, setup.py, pyproject.toml), and remove pins that existed only to keep Flask-RESTPlus importable, such as an old Werkzeug. Search the code and config for every RESTPLUS_ setting and for ERROR_404_HELP, and rename each to the key Flask-RESTX reads (RESTX_VALIDATE, RESTX_MASK_SWAGGER, RESTX_MASK_HEADER, RESTX_JSON, RESTX_ERROR_404_HELP); list any setting you could not map. If upgrading pulled in newer majors of Flask, Werkzeug or Flask-SQLAlchemy, fix what they break and name each fix separately. Run the test suite if there is one. If there is none, write a script using the Flask test client that calls every route once with valid input and once with invalid input, and confirm that request validation still rejects a body missing a required field, that marshalled responses keep their fields, and that swagger.json is served. Do not rename the project's own modules or constants. Open a pull request that lists the renamed settings, the fixes caused by other upgraded packages, and the output of the route checks.",
  "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 with a small diff and a description that carries the weight. For rest_api_demo the code change is five import lines, three config keys in `app.py`, two `paginate` calls, and the pins in `requirements.txt` and `setup.py`. The description separates three kinds of change: the rename, the settings Flask-RESTX would have ignored, and the fixes that belong to Flask-SQLAlchemy 3 and not to this migration at all.

It also includes the route check as a table: each route, the input, the status before the settings fix and after. The row a reviewer should read first is the invalid `POST`, because it is the one that a rename-only migration gets wrong without any error. If the project had no working baseline, the description states that the comparison is against the documented behaviour, not against a run of the old code.

Before merging, the reviewer decides whether to keep the unpinned versions the agent chose or pin them, and whether the new check script should stay in the repository as a first test.

## Run it on every GitHub issue labelled flask-restx

Teams with several small Flask services usually move them one at a time. Open a tracking issue in each repository, then add an automation to that repository's Project with a `github` trigger on `issues.labeled` and the `labels` filter set to `flask-restx`, and save the prompt above. Only a label applied by an owner, member or collaborator of the repository fires the trigger. The issue text is placed after the saved prompt as event data, so it can carry notes the prompt cannot know, such as which clients depend on the exact shape of validation errors.

If you would rather start the batch from a script, send one `POST /o/{org}/sessions` per repository with the body above and a `request_id` that is a UUID v5 of the repository name, so running the script twice starts nothing twice.

## Why run it on Rush?

The dangerous part of this migration produces no error. A config key that the new library does not read is still a valid config key, the app starts, the Swagger page renders, and request validation is off. Finding that takes sending a bad request and looking at the answer, which is a step people skip when the diff is five import lines. The agent sends it, in a sandbox with a fresh install of current packages, and the request and response are kept in the session transcript.

A fresh install is also the honest environment for this job. A developer's virtualenv for an old Flask-RESTPlus project often still works only because it was created years ago. The sandbox starts empty, so the pull request describes what a new clone or a rebuilt image will meet, including the unrelated breakages from Flask-SQLAlchemy that arrive with the same upgrade.

## Frequently asked questions

### Is Flask-RESTX a drop-in replacement for Flask-RESTPlus?

For the Python API, nearly: the classes and decorators keep their names, so changing `flask_restplus` to `flask_restx` is usually enough to import. The configuration is not drop-in. Settings prefixed `RESTPLUS_` are ignored, so validation and field masks can change behaviour with no error.

### Which settings do I have to rename?

`RESTPLUS_VALIDATE`, `RESTPLUS_MASK_SWAGGER`, `RESTPLUS_MASK_HEADER` and `RESTPLUS_JSON` become the same names with a `RESTX_` prefix. `ERROR_404_HELP` becomes `RESTX_ERROR_404_HELP`; the old name is still read, with a deprecation warning. `SWAGGER_UI_DOC_EXPANSION` is unchanged.

### Why does my old project fail with an ImportError before I change anything?

Old Flask-RESTPlus releases only run on old Flask and Werkzeug, and those in turn depend on packages they did not pin. A fresh install picks a current MarkupSafe that no longer has `soft_unicode`, or a Werkzeug without `cached_property` at the top level. Moving to Flask-RESTX lets you drop the old pins instead of adding more.

### Will my Swagger documentation change?

The generated `swagger.json` keeps the same paths, models and namespaces. The agent fetches it after the migration and reports differences if the project had a working baseline to compare with. The mask header parameter appears or disappears depending on `RESTX_MASK_SWAGGER`, which is one more reason to rename that key.

### Does the agent upgrade Flask and SQLAlchemy too?

Only as far as the new pins require. Removing an old Werkzeug pin usually brings in current Flask and Flask-SQLAlchemy, and the agent fixes what breaks, such as positional arguments to `paginate`. Each of those fixes is listed apart from the Flask-RESTX changes so you can see which upgrade caused it.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From Flask-Script to the Flask CLI](https://getrush.ai/run/migrate-flask-script-to-flask-cli/flask-script/)
- [Migrate From garyburd/redigo to gomodule/redigo](https://getrush.ai/run/migrate-garyburd-redigo-to-gomodule-redigo/redigo/)
- [Migrate a Go Test Suite From Ginkgo v1 to Ginkgo v2](https://getrush.ai/run/migrate-ginkgo-v1-to-v2/ginkgo/)
- [Replace go-bindata With go:embed in a Go Web Server](https://getrush.ai/run/migrate-go-bindata-to-embed/go-bindata/)
- [Replace mitchellh/go-homedir With os.UserHomeDir in a Go CLI](https://getrush.ai/run/migrate-go-homedir-to-os-userhomedir/go-homedir/)
- [Replace hashicorp/go-multierror With errors.Join in a Go Project](https://getrush.ai/run/migrate-go-multierror-to-errors-join/go-multierror/)

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