Install & Compatibility
Where this runs
tested against v0.15.16 · 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.915 runs
installs and imports cleanly · install 0.0s · import 1.407s · 59.6MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 4.7s · import 1.297s · 57MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Page
✓ from fastapi_pagination import Page
add_pagination
✓ from fastapi_pagination import add_pagination
paginate
✓ from fastapi_pagination import paginate
✗ from fastapi_pagination.ext.some_orm import paginate
Use 'from fastapi_pagination import paginate' for in-memory lists; use 'from fastapi_pagination.ext.some_orm import paginate' for database queries to avoid loading all data into memory.
apaginate
✓ from fastapi_pagination import apaginate
For async operations, `apaginate` is the recommended function. The `paginate` function's async support will be removed in a future major version.
This quickstart demonstrates basic page-based pagination for an in-memory list. Define your response model with `Page[YourModel]`, call `add_pagination(app)`, and use `paginate()` on your data. For database-backed pagination, use the `paginate` function from the relevant `ext` module (e.g., `fastapi_pagination.ext.sqlalchemy`).
from fastapi import FastAPI
from pydantic import BaseModel, Field
from fastapi_pagination import Page, add_pagination, paginate
app = FastAPI()
add_pagination(app)
class UserOut(BaseModel):
name: str = Field(..., example="Steve")
surname: str = Field(..., example="Jobs")
# Simulate a database/data source
users_db = [
{"name": "John", "surname": "Doe"},
{"name": "Jane", "surname": "Smith"},
{"name": "Peter", "surname": "Jones"},
{"name": "Alice", "surname": "Brown"},
{"name": "Bob", "surname": "White"},
{"name": "Charlie", "surname": "Green"},
{"name": "Diana", "surname": "Black"},
{"name": "Eve", "surname": "Red"},
{"name": "Frank", "surname": "Blue"},
{"name": "Grace", "surname": "Yellow"},
]
@app.get("/users", response_model=Page[UserOut])
async def get_users():
# paginate function processes the data to return a Page object
return paginate(users_db)
# To run this example:
# 1. Save as main.py
# 2. Run: uvicorn main:app --reload
# 3. Access in browser: http://127.0.0.1:8000/users?page=1&size=5
Debug
Known issues
deprecatedSeveral database extensions have been deprecated in version 0.15.7, including `bunnet`, `databases`, `gino`, `odmantic`, and `orm`. Users should migrate to actively maintained extensions like `sqlalchemy`, `sqlmodel`, or `beanie` if possible.fixReview the official documentation for recommended alternatives and update imports and pagination logic accordingly. Some deprecated modules from v0.13.x (e.g., `async_sqlalchemy`) require switching to `fastapi_pagination.ext.sqlalchemy`.
affects: >=0.15.7
breakingThe `paginate` function for async operations will be removed in a future major version. The dedicated `apaginate` function should be used for async calls to ensure forward compatibility.fixReplace `paginate()` with `apaginate()` for all asynchronous pagination calls. Ensure your code imports `apaginate` correctly (`from fastapi_pagination import apaginate`).
affects: Future major versions (currently deprecated, but functionally working)
gotchaUsing the default `paginate` function (i.e., `from fastapi_pagination import paginate`) on database queries will load all data into memory before paginating, leading to performance issues and high memory consumption for large datasets.fixFor database interactions, always use the `paginate` function from the specific `fastapi_pagination.ext.<orm_name>` module (e.g., `from fastapi_pagination.ext.sqlalchemy import paginate`) to leverage database-side pagination.
affects: All versions
breakingIn version 0.13.x, the `Page.create` class method signature changed; the `total` argument is now keyword-only.fixUpdate calls to `Page.create` to pass `total` as a keyword argument (e.g., `Page.create(items=my_items, total=total_count)`).
affects: >=0.13.0
gotchaWhile `fastapi-pagination` generally supports Pydantic V2, earlier versions of `fastapi-pagination` (pre-0.15.8) or specific Pydantic V2 minor versions (e.g., Pydantic <2.12.5) might encounter compatibility issues. FastAPI itself had a migration path from Pydantic V1 to V2, and users should ensure their FastAPI version is compatible with Pydantic V2.fixEnsure `fastapi-pagination` is updated to the latest version (0.15.8 or newer) and `FastAPI` is also a recent version that explicitly supports Pydantic V2 (e.g., FastAPI >=0.100.0). Consult Pydantic's official migration guide for general Pydantic V2 migration steps.
affects: <0.15.8 and potentially specific Pydantic V2 sub-versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fastapi_pagination'
The 'fastapi-pagination' library is not installed in your current Python environment or the environment is not activated.
fixRun 'pip install fastapi-pagination' in your terminal to install the library. If using a virtual environment, ensure it's activated before installation and running your application.
RuntimeError: Use params or add_pagination
This error occurs when the 'add_pagination(app)' function, which initializes the pagination middleware, is not called, or it's called before all your FastAPI routers have been included.
fixEnsure that 'add_pagination(app)' is called once in your main FastAPI application file, specifically *after* all 'app.include_router()' calls.
TypeError: 'type' object is not subscriptable
This issue typically arises when using Python versions older than 3.9 (such as 3.7 or 3.8) with generic type hints like 'Page[MyModel]' without enabling postponed evaluation of annotations.
fixUpgrade your Python version to 3.9 or higher, or add 'from __future__ import annotations' at the very top of your Python file(s) where generic types are used.
AttributeError: 'NoneType' object has no attribute 'total'
This error often indicates that the pagination function (especially ORM-specific ones like for SQLAlchemy) received a 'None' value or an incorrectly constructed query object instead of an executable query that can determine the total count of items. This might happen if the query execution fails or returns no results unexpectedly before pagination is applied.
fixEnsure that the database query (e.g., SQLAlchemy 'select' statement) is correctly built, executed, and passed to the appropriate 'paginate' function (e.g., 'fastapi_pagination.ext.sqlalchemy.paginate'). Verify that the query is not returning 'None' or an empty result prematurely, and that the ORM extension is correctly handling the total count calculation.
Upgrade
Version history
0.15.16latest on PyPI · released Jul 28, 2026
Audit
Dependencies
fastapirequiredCore web framework dependency.
pydanticrequiredUsed for data validation and serialization of models.
sqlalchemyoptionalOptional dependency for SQLAlchemy ORM integration.
tortoise-ormoptionalOptional dependency for Tortoise-ORM integration.
pymongooptionalOptional dependency for PyMongo integration (often via Beanie/Motor).
sqlakeysetoptionalOptional dependency for keyset pagination with SQLAlchemy.