Install & Compatibility
Where this runs
tested against v1.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.704s · 36.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.662s · 36MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Api
✓ from flask_restx import Api
Resource
✓ from flask_restx import Resource
fields
✓ from flask_restx import fields
Namespace
✓ from flask_restx import Namespace
reqparse
✓ from flask_restx import reqparse
While correct, `reqparse` is deprecated and will be removed in a future major version (2.0). Consider using alternatives like `api.model()` or `marshmallow` for request parsing.
Api
✓ from flask_restx import Api
✗ from flask_restplus import Api
Flask-RESTX is a fork of Flask-RESTPlus; imports must be updated from `flask_restplus` to `flask_restx`.
This quickstart demonstrates a basic Flask-RESTX application with a single API, a namespace, and a resource for managing 'todo' items. It includes defining a data model, handling GET, POST, PUT, and DELETE operations, and leverages Flask-RESTX's automatic Swagger UI documentation features.
from flask import Flask
from flask_restx import Api, Resource, fields
app = Flask(__name__)
api = Api(app, version='1.0', title='Example API', description='A simple API example')
# Define a namespace
ns = api.namespace('todos', description='TODO operations')
# Define a model for request/response serialization
todo_model = ns.model('Todo', {
'id': fields.Integer(readonly=True, description='The task unique identifier'),
'task': fields.String(required=True, description='The task details')
})
# A simple in-memory data store
class TodoDAO:
def __init__(self):
self.counter = 0
self.todos = []
def get(self, id):
for todo in self.todos:
if todo['id'] == id:
return todo
ns.abort(404, "Todo {} doesn't exist".format(id))
def create(self, data):
todo = data
self.counter += 1
todo['id'] = self.counter
self.todos.append(todo)
return todo
def update(self, id, data):
todo = self.get(id)
todo.update(data)
return todo
def delete(self, id):
todo = self.get(id)
self.todos.remove(todo)
DAO = TodoDAO()
DAO.create({'task': 'Build an API'})
DAO.create({'task': '?????'})
DAO.create({'task': 'profit!'})
@ns.route('/<int:id>')
@ns.param('id', 'The task identifier')
class Todo(Resource):
@ns.doc('get_todo')
@ns.marshal_with(todo_model)
def get(self, id):
'''Fetch a single todo item'''
return DAO.get(id)
@ns.doc('update_todo')
@ns.expect(todo_model)
@ns.marshal_with(todo_model)
def put(self, id):
'''Update a todo item given its identifier'''
return DAO.update(id, api.payload)
@ns.doc('delete_todo')
@ns.response(204, 'Todo deleted')
def delete(self, id):
'''Delete a todo item given its identifier'''
DAO.delete(id)
return '', 204
@ns.route('/')
class TodoList(Resource):
@ns.doc('list_todos')
@ns.marshal_list_with(todo_model)
def get(self):
'''List all todo items'''
return DAO.todos
@ns.doc('create_todo')
@ns.expect(todo_model)
@ns.marshal_with(todo_model, code=201)
def post(self):
'''Create a new todo item'''
return DAO.create(api.payload), 201
if __name__ == '__main__':
app.run(debug=True)
Debug
Known issues
breakingBreaking changes related to Flask and Werkzeug versions. Prior to `flask-restx` 0.4.0, versions were incompatible with Flask/Werkzeug 2.0.0+. Version 0.4.0 pinned dependencies to `<2.0.0`. Versions 0.5.0 to <1.3.0 provided compatibility with Flask <3.0.0 by wrapping imports. `flask-restx` >=1.3.0 adds support for Flask >=3.0.0 and Flask >=2.0.0.fixUpgrade to `flask-restx` 1.3.0 or newer for Flask 2.x/3.x compatibility. For older `flask-restx` versions (<=0.4.0), pin Flask and Werkzeug to `<2.0.0`.
affects: <1.3.0
breakingPython version compatibility has changed. Support for Python <3.7 was dropped in versions 1.0.1 and 1.2.0. The current minimum Python version required is 3.9.fixEnsure your project uses Python 3.9 or higher. If using older Python versions, you must use an older `flask-restx` release (e.g., <1.0.1 for Python <3.7).
affects: <1.2.0
deprecatedThe `reqparse` module is considered deprecated and is slated for removal in Flask-RESTX 2.0. While still functional, it is recommended to transition to `api.model()` for request validation and serialization, or integrate with other input/output validation libraries like Marshmallow.fixReplace `reqparse.RequestParser()` with `api.model()` definitions and `@ns.expect()` decorator for request payload validation and documentation.
affects: All versions
gotchaWhen migrating from `Flask-RESTPlus`, all imports from `flask_restplus` must be changed to `flask_restx`. Additionally, configuration options (e.g., `RESTPLUS_SWAGGER_UI_DOC_EXPANSION`) should be updated from `RESTPLUS_` prefixes to `RESTX_`.fixUse a global find/replace tool to change `flask_restplus` to `flask_restx` in Python files and `RESTPLUS_` to `RESTX_` in configuration settings.
affects: All versions (for migration)
gotchaDeploying Flask-RESTX applications behind a reverse proxy (like Nginx) with `werkzeug.middleware.proxy_fix.ProxyFix` can lead to issues where the Swagger UI interface incorrectly assumes its base paths (e.g., `/swaggerui`, `/api/swagger.json`), even if the API itself functions correctly under the proxy. This often requires complex Nginx configurations or serving Swagger UI assets statically.fixCarefully configure `ProxyFix` and, if issues persist, consider serving the Swagger UI static assets manually and configuring `specs_url` or `doc` parameters in `Api` initialization.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flask.scaffold'
This error occurs when using Flask-RESTX with Flask versions 3.0.0 or higher, because the 'flask.scaffold' module was moved or removed in newer Flask versions.
fixTo resolve this, either downgrade Flask to a version below 3.0.0 (e.g., `pip install 'Flask<3.0.0'`) or update Flask-RESTX to version 1.2.0 or higher, which includes compatibility fixes for Flask 3.x.
AttributeError: module 'flask_restx.api' has no attribute 'doc'
This error typically happens when attempting to use the `@api.doc()` decorator directly on the `api` instance imported from `flask_restx`, instead of applying it to a `Namespace` instance or a `Resource` class within a namespace.
fixEnsure you are applying `@ns.doc()` (where `ns` is a `Namespace` instance) to your `Resource` classes or their methods, or use `@api.route('/path')` directly on the `Api` instance for basic routes. AttributeError: 'Api' object has no attribute 'add_resource'
Developers migrating from Flask-RESTful or older Flask-RESTPlus examples often try to use `api.add_resource()` directly on the `Api` object, but `flask-restx` primarily uses namespaces for resource registration, where `add_resource` is a method of the `Namespace` object.
fixInstead of `api.add_resource()`, define a `Namespace` and add your resource to it using `ns.add_resource()`, or use the `@api.route()` decorator on the `Api` instance for simple, non-namespaced resources.
TypeError: The view function did not return a valid response. The return type must be a string, dict, tuple, Response instance, or WSGI callable, but it was a HelloWorld
This error occurs when a method in a `flask_restx.Resource` class returns an instance of a class or an unexpected type, rather than a dictionary, string, tuple, or Flask `Response` object that Flask-RESTX can serialize.
fixEnsure that your `Resource` methods explicitly return a dictionary, string, or a `flask.Response` object, which Flask-RESTX can then automatically serialize to JSON. If using classes as return types, they must be marshaled using `api.model` and `@marshal_with`.
ModuleNotFoundError: No module named 'flask_restplus'
This error indicates that the project is still attempting to import from the deprecated `flask_restplus` library after it has been migrated to `flask-restx`.
fixUpdate all import statements in your project from `from flask_restplus import ...` to `from flask_restx import ...`. You can often do this with a global search and replace in your IDE or a `sed` command.
Upgrade
Version history
1.3.2latest on PyPI · released Sep 23, 2025
Audit
Dependencies
FlaskrequiredCore web framework dependency for building REST APIs.
WerkzeugrequiredWSGI utility library, a core dependency of Flask, with specific compatibility requirements for Flask-RESTX.