{"id":2499,"library":"fastapi-pagination","title":"FastAPI Pagination","description":"fastapi-pagination is a Python library designed to simplify pagination in FastAPI applications. It provides utility functions and data models to paginate database queries and return paginated responses, supporting various strategies like page-based, limit-offset, and cursor-based pagination. The library is actively maintained, with frequent minor releases, and is currently at version 0.15.12.","status":"active","version":"0.15.12","language":"en","source_language":"en","source_url":"https://github.com/uriyyo/fastapi-pagination","tags":["fastapi","pagination","api","database","orm"],"install":[{"cmd":"pip install \"fastapi-pagination[full]\"","lang":"bash","label":"Full Installation (includes common database extensions)"},{"cmd":"pip install fastapi-pagination","lang":"bash","label":"Basic Installation"},{"cmd":"pip install fastapi-pagination[sqlalchemy]","lang":"bash","label":"With SQLAlchemy Extension"}],"dependencies":[{"reason":"Core web framework dependency.","package":"fastapi"},{"reason":"Used for data validation and serialization of models.","package":"pydantic","optional":false},{"reason":"Optional dependency for SQLAlchemy ORM integration.","package":"sqlalchemy","optional":true},{"reason":"Optional dependency for Tortoise-ORM integration.","package":"tortoise-orm","optional":true},{"reason":"Optional dependency for PyMongo integration (often via Beanie/Motor).","package":"pymongo","optional":true},{"reason":"Optional dependency for keyset pagination with SQLAlchemy.","package":"sqlakeyset","optional":true}],"imports":[{"symbol":"Page","correct":"from fastapi_pagination import Page"},{"symbol":"add_pagination","correct":"from fastapi_pagination import add_pagination"},{"note":"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.","wrong":"from fastapi_pagination.ext.some_orm import paginate","symbol":"paginate","correct":"from fastapi_pagination import paginate"},{"note":"For async operations, `apaginate` is the recommended function. The `paginate` function's async support will be removed in a future major version.","symbol":"apaginate","correct":"from fastapi_pagination import apaginate"}],"quickstart":{"code":"from fastapi import FastAPI\nfrom pydantic import BaseModel, Field\nfrom fastapi_pagination import Page, add_pagination, paginate\n\napp = FastAPI()\nadd_pagination(app)\n\nclass UserOut(BaseModel):\n    name: str = Field(..., example=\"Steve\")\n    surname: str = Field(..., example=\"Jobs\")\n\n# Simulate a database/data source\nusers_db = [\n    {\"name\": \"John\", \"surname\": \"Doe\"},\n    {\"name\": \"Jane\", \"surname\": \"Smith\"},\n    {\"name\": \"Peter\", \"surname\": \"Jones\"},\n    {\"name\": \"Alice\", \"surname\": \"Brown\"},\n    {\"name\": \"Bob\", \"surname\": \"White\"},\n    {\"name\": \"Charlie\", \"surname\": \"Green\"},\n    {\"name\": \"Diana\", \"surname\": \"Black\"},\n    {\"name\": \"Eve\", \"surname\": \"Red\"},\n    {\"name\": \"Frank\", \"surname\": \"Blue\"},\n    {\"name\": \"Grace\", \"surname\": \"Yellow\"},\n]\n\n@app.get(\"/users\", response_model=Page[UserOut])\nasync def get_users():\n    # paginate function processes the data to return a Page object\n    return paginate(users_db)\n\n# To run this example:\n# 1. Save as main.py\n# 2. Run: uvicorn main:app --reload\n# 3. Access in browser: http://127.0.0.1:8000/users?page=1&size=5","lang":"python","description":"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`)."},"warnings":[{"fix":"Review 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`.","message":"Several 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.","severity":"deprecated","affected_versions":">=0.15.7"},{"fix":"Replace `paginate()` with `apaginate()` for all asynchronous pagination calls. Ensure your code imports `apaginate` correctly (`from fastapi_pagination import apaginate`).","message":"The `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.","severity":"breaking","affected_versions":"Future major versions (currently deprecated, but functionally working)"},{"fix":"For 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.","message":"Using 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update calls to `Page.create` to pass `total` as a keyword argument (e.g., `Page.create(items=my_items, total=total_count)`).","message":"In version 0.13.x, the `Page.create` class method signature changed; the `total` argument is now keyword-only.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Ensure `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.","message":"While `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.","severity":"gotcha","affected_versions":"<0.15.8 and potentially specific Pydantic V2 sub-versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}