Installation

This guide covers all installation options for pypaginate.

Requirements

  • Python 3.11 or higher

  • pip or uv package manager

Basic Installation

uv add pypaginate

pip install pypaginate

The base package includes in-memory pagination, filtering specs, sorting specs, and search specs with no heavy dependencies beyond pydantic.

Installation with Extras

SQLAlchemy Support

For database pagination (offset and cursor/keyset) with SQLAlchemy 2.0+:

uv add pypaginate[sqlalchemy]

pip install pypaginate[sqlalchemy]

Includes:

  • SQLAlchemy[asyncio]>=2.0.0 – ORM and async database toolkit (includes built-in cursor/keyset pagination)

Search Features

Fuzzy text search is built into the native engine – it always works with the base install, no extra dependency required.

The pypaginate[search] extra is a no-op kept only for backward compatibility (it no longer installs anything):

uv add pypaginate[search]

pip install pypaginate[search]

FastAPI Integration

For FastAPI dependency injection (OffsetDep, CursorDep, FilterDep, etc.):

uv add pypaginate[fastapi]

pip install pypaginate[fastapi]

Includes:

  • fastapi>=0.95.0 – FastAPI framework

Fast Mode (msgspec)

For near-zero-overhead page construction using msgspec structs:

uv add pypaginate[fast]

pip install pypaginate[fast]

Includes:

  • msgspec>=0.18.0 – Fast serialization

All Features

Install everything at once:

uv add pypaginate[all]

pip install pypaginate[all]

Development Installation

For contributing to pypaginate:

git clone https://github.com/CybLow/paginate.git
cd pypaginate
uv sync

This installs all optional dependencies plus testing, linting, and documentation tools.

Verifying Installation

>>> import pypaginate
>>> pypaginate.__version__
'0.2.0'

>>> from pypaginate import paginate, OffsetParams
>>> page = paginate([1, 2, 3, 4, 5], OffsetParams(page=1, limit=2))
>>> page.items
[1, 2]
>>> page.total
5

Check Optional Dependencies

# Check SQLAlchemy support
>>> from pypaginate.adapters.sqlalchemy import SQLAlchemyBackend
>>> # No ImportError = SQLAlchemy is installed

# Check FastAPI support
>>> from pypaginate.adapters.fastapi import OffsetDep, FilterDep
>>> # No ImportError = FastAPI is installed

# Check fast mode
>>> from pypaginate.domain.fast_pages import FastOffsetPage
>>> # No ImportError = msgspec is installed

Troubleshooting

ImportError: FastAPI Features

If you see:

ImportError: FastAPI is required: pip install pypaginate[fastapi]

Solution:

pip install pypaginate[fastapi]

ImportError: SQLAlchemy

If you get import errors for pypaginate.adapters.sqlalchemy:

pip install pypaginate[sqlalchemy]

Version Conflicts

If you have version conflicts:

uv venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

pip install pypaginate[all]

Next Steps