NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #2047 most downloaded on PyPI
FastAPI pagination
Last release 18 days ago
16 Sep 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
98 releases · first in 2020
One column per quarter.
If you are upgrading from v0.15 , please read the v0.16 migration guide — this release contains breaking changes.
v0.16.0 is the first stable release of the v0.16 line.
If you are upgrading from v0.15, please read the v0.16 migration guide —
this release contains breaking changes.
bind_params and execute_options for sqlalchemy/sqlmodelpaginate/apaginate from fastapi_pagination.ext.sqlalchemy and fastapi_pagination.ext.sqlmodel
now accept bind_params and execute_options, which are applied to every statement that is executed
(both the items query and the count query).
from sqlalchemy import bindparam, select
from fastapi_pagination.ext.sqlalchemy import paginate
paginate(
session,
select(User).where(User.age > bindparam("min_age")),
bind_params={"min_age": 18},
execute_options={"populate_existing": True},
)pydantic v1 support was droppedpydantic package now requires version 2.13.4 or higher.
UsePydanticV1 customization and all version specific helpers from fastapi_pagination.pydantic
were removed.
paginate functions were removedAsync paginate functions, that were deprecated in v0.15.0, are now removed.
Please use apaginate instead.
# before
from fastapi_pagination.ext.sqlalchemy import paginate
# after
from fastapi_pagination.ext.sqlalchemy import apaginatemotor, odmantic, bunnet, databases, orm, gino and pony extensions were removed,
together with their extras.
Please use fastapi_pagination.ext.pymongo instead of motor/odmantic/bunnet
and fastapi_pagination.ext.sqlalchemy instead of databases/orm/gino.
fastapi package now requires version 0.140.13 or higher, piccolo - 1.0 or higher.
elasticsearch extra now installs elasticsearch>=8.18.0 instead of elasticsearch-dsl.
2. Deprecated async paginate functions were removed
First beta version of v0.16.0 version.
pydantic v1 support was droppedpydantic package now requires version 2.13.4 or higher.
UsePydanticV1 customization and all version specific helpers from fastapi_pagination.pydantic
were removed.
paginate functions were removedAsync paginate functions, that were deprecated in v0.15.0, are now removed.
Please use apaginate instead.
# before
from fastapi_pagination.ext.sqlalchemy import paginate
# after
from fastapi_pagination.ext.sqlalchemy import apaginatemotor, odmantic, bunnet, databases, orm, gino and pony extensions were removed,
together with their extras.
Please use fastapi_pagination.ext.pymongo instead of motor/odmantic/bunnet
and fastapi_pagination.ext.sqlalchemy instead of databases/orm/gino.
fastapi package now requires version 0.140.13 or higher, piccolo - 1.0 or higher.
elasticsearch extra now installs elasticsearch>=8.18.0 instead of elasticsearch-dsl.
Support new fastapi version 0.140.5+. #1990
Fix compatibility issue with fastapi 0.137.0 #1930
Add UseFlattenPage customizer. #1905
Add SQLAlchemy 2.1 support using TypeVarTuple for Row type compatibility. #1843
SQLAlchemy 2.1 support using TypeVarTuple for Row type compatibility. #1843inline_count parameter for single-query pagination. #1876additional_data parameter. #1888peewee integration. #1838Thanks to @rhynzler, @emfpdlzj, @rleyton and @NatanKonig !
Full Changelog: 0.15.12...0.15.13
Add missed unique argument to sqlakeyset.select_page method. #1822
unique argument to sqlakeyset.select_page method. #1822Full Changelog: 0.15.11...0.15.12
Add integration with async sqlakeyset #1811
sqlakeyset #1811Full Changelog: 0.15.10...0.15.11
Avoid unconditional SQLAlchemy import in ext.psycopg . #1745 Thanks to @narushev-core
SQLAlchemy import in ext.psycopg. #1745 Thanks to @narushev-corepsycopg ext. #1746Full Changelog: 0.15.9...0.15.10
Fix Incompatibility issue with beanie>2 and pymongo async. #1733
beanie>2 and pymongo async. #1733pydantic v2 and custom params. #1732Full Changelog: 0.15.8...0.15.9
Simplify pydantic v2 param handling, support keyword aliases. #1720
pydantic v2 param handling, support keyword aliases. #1720Full Changelog: 0.15.7...0.15.8
Deprecate bunnet, databases, gino, odmantic, and orm extensions.
bunnet, databases, gino, odmantic, and orm extensions.Full Changelog: https://github.com/uriyyo/fastapi-pagination/compare/0.15.6...0.15.7
Add deprecation warnings for old pydantic and FastAPI versions. #1710
psycopg integration. #1708pydantic and FastAPI versions. #1710beanie $project into $facet. #1711Full Changelog: https://github.com/uriyyo/fastapi-pagination/compare/0.15.5...0.15.6
Fix issue with missed metadata for pydantic fields. #1703
pydantic fields. #1703Full Changelog: https://github.com/uriyyo/fastapi-pagination/compare/0.15.4...0.15.5
Exclude pydantic>=2.12.5 from legacy v2 BaseModel handling. #1691
pydantic>=2.12.5 from legacy v2 BaseModel handling. #1691Full Changelog: https://github.com/uriyyo/fastapi-pagination/compare/0.15.3...0.15.4
Defer pydantic.v1 import until it is actually being used. #1676
Use AsyncItemsTransformer type annotation in piccolo ext. #1666
AsyncItemsTransformer type annotation in piccolo ext. #1666Add support for pydantic.v1. #1658
Remove deprecation warning for sqlalchemy.orm.Query.
Fix deprecation warning for python 3.14. #1601 (Thanks to @nphilipp 🙌)
Fix compatibility issue with FastAPI v0.118.0. #1599
v0.118.0. #1599Fix falsy callable handling in length_function parameter. #1584
length_function parameter. #1584total field now becomes required in Page and LimitOffsetPage classes. It was previously optional, but now it is required for non-optional pages.
total becomes required by defaulttotal field now becomes required in Page and LimitOffsetPage classes.
It was previously optional, but now it is required for non-optional pages.
UseIncludeTotal updates total field type.UseIncludeTotal customization now updates total field to required or optional based on its value.
CursorPage now includes total field by defaultCursorPage class now includes total field by default.
Now all pages have same default behavior regarding total field.
You can still use UseIncludeTotal to disable total field in CursorPage.
from typing import TypeVar
from fastapi_pagination.cursor import CursorPage
from fastapi_pagination.customization import UseIncludeTotal, CustomizedPage
T = TypeVar("T")
CursorPageNoTotal = CustomizedPage[
CursorPage[T],
UseIncludeTotal(False),
]
beanie min version updatebeanie package now requires version 2.0.0 or higher.
First beta version of v0.14.0 version.
First beta version of v0.14.0 version.
total becomes required by defaulttotal field now becomes required in Page and LimitOffsetPage classes.
It was previously optional, but now it is required for non-optional pages.
UseIncludeTotal updates total field type.UseIncludeTotal customization now updates total field to required or optional based on its value.
CursorPage now includes total field by defaultCursorPage class now includes total field by default.
Now all pages have same default behavior regarding total field.
You can still use UseIncludeTotal to disable total field in CursorPage.
from typing import TypeVar
from fastapi_pagination.cursor import CursorPage
from fastapi_pagination.customization import UseIncludeTotal, CustomizedPage
T = TypeVar("T")
CursorPageNoTotal = CustomizedPage[
CursorPage[T],
UseIncludeTotal(False),
]
beanie min version updatebeanie package now requires version 2.0.0 or higher.
Add pymongo aggregate paginate functions. #1540
pymongo aggregate paginate functions. #1540Add async pymongo integration. #1544
Fix issue with greenlet_spawn when using async sqlalchemy apaginate. #1527
Please, follow the migration guideline here
Rename async paginate to apaginate. #1512
* Add flows. #1471 * Connect params and page. #1504
A first alpha version of 0.13.x 🙏
Add ability to quote/unquote cursor. #1403
Add BaseSelect type hint for SQLModel paginate. #1365
Add support for sqlalchemy CompoundSelect. #1361
sqlalchemy CompoundSelect. #1361Add NotImplementedError to ignored exc when resolving unwrap-mode. #1324
NotImplementedError to ignored exc when resolving unwrap-mode. #1324Fix issue when select model with single field. #1317
select model with single field. #1317NOTE! This is last release before 0.13.0 version.
Fix issue with sqlalchemy scalar select detection. #1313
sqlalchemy unwrap_mode allows you to control how to unwrap result rows before passing them to items transformer
and page creation.
unwrap_mode can be set to one of the following values:
None - will use auto mode for default queries, and legacy for text and from_statement queries."auto" - will unwrap only in case if you are selecting single model."legacy" - will use old behavior, where row will be unwrapped if it contains only one element."unwrap" - will always unwrap row, even if it contains multiple elements."no-unwrap" - will never unwrap row, even if it contains only one element.Add better logic for sqlalchemy scalars unwrapping. #1281
sqlalchemy scalars unwrapping. #1281sqlalchemy imports for gino ext. #1282sqlachemy extension no longer requires to use items_transformer when selecting scalar field:
This code is no longer valid:
paginate(session, select(User.name), transformer=lambda items: [{'name': item} for item in items])
The correct version now is:
paginate(session, select(User.name))
Bump to next pytest-asyncio version. #1118
Fix issue with passing count_query into sqlalchemy/sqlmodel. #1194
Fix issue with databases + sqlalchemy 2.0. #1160
Improve resolve_params exc message. #1129
Add limit to CursorParams.size field. #1119
_WARNING_MSG. #1117Thanks to @barsikus007 and @frost-nzcr4!
CursorPage now has default upper limit for size query param (size should be <= 100).
If you want to remove this restriction and use old behavior, you can customize CursorPage:
from fastapi_pagination.cursor import CursorPage as BaseCursorPage
from fastapi_pagination.customization import UseParamsFields, CustomizedPage
CursorPage = CustomizedPage[
BaseCursorPage,
UseParamsFields(
size=Query(50, ge=0),
),
]
Fix issue when custom OpenAPI schema is overrided. #1105
Return fastapi.ext.sqlalchemy.paginate_query function. #1093
fastapi.ext.sqlalchemy.paginate_query function. #1093Add ability to paginate raw sqlalchemy queries. #1085
sqlalchemy queries. #1085Suppress undefined annotation exception for pydantic v2. #1069
pydantic v2. #1069Add better exception message for sqlalchemy non-hashable rows. #1048
sqlalchemy non-hashable rows. #1048Current release changes way how to customize page. New customization allows to customize pages in typing-compatible way that will not require to use # type: ignore or if TYPE_CHECKING workarounds, for more information, please check docs - link.
Old way
from fastapi_pagination import Page
CustomPage = Page.with_custom_options(
cls_name="CustomPage",
size=10,
)
New way:
from fastapi_pagination import Page
from fastapi_pagination.customization import CustomizedPage, UseName, UseParamsFields
CustomPage = CustomizedPage[
Page,
UseName("CustomPage"),
UseParamsFields(size=10),
]
Add async analog of default paginate. #1039
* Add set_params function. #1029
set_params function. #1029Add python 3.12 official support. #1023
Fix issue with default value fitler_field for pymongo. #955
* Bump sqlmodel version. #933
sqlmodel version. #933Remove usage of deprecated pydantic v2 field. #896
Add ability to use async_scoped_session. #877
Fix issue where Pydantic2 would raise warnings when arbitrary keywords are set. #848
Fix issue with links.Page/links.LimitOffsetPage revalidation. ( #796, #799 )
Fix issue with pydantic v2 params validation. #781
Fixed warnings with GenericModel. #767
Add current_page and current_page_backwards parameters to cursor-based pagination. #745
Your coding agent can read these notes before it upgrades. Set up the MCP server →