Install & Compatibility
Where this runs
tested against v2024.4.12 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.493s · 22.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.3s · import 0.455s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pagination
✓ from flask_paginate import Pagination
The primary class for creating pagination objects.
get_page_parameter
✓ from flask_paginate import get_page_parameter
Utility to get the page argument from request parameters, supporting custom argument names.
get_per_page_parameter
✓ from flask_paginate import get_per_page_parameter
Utility to get the per_page argument from request parameters.
This quickstart sets up a basic Flask application with pagination for a list of 100 users. It demonstrates how to retrieve the current page number, slice the data accordingly, and initialize the `Pagination` object. It uses Bootstrap 4 for styling and renders the pagination controls directly using `pagination.render_macro('pagination.html')`.
import os
from flask import Flask, render_template, request
from flask_paginate import Pagination, get_page_parameter
app = Flask(__name__)
app.secret_key = os.environ.get('FLASK_SECRET_KEY', 'a_secret_key_for_dev')
# Sample data
USERS = [str(i) for i in range(1, 101)]
@app.route('/')
def index():
page = request.args.get(get_page_parameter(), type=int, default=1)
per_page = 10
offset = (page - 1) * per_page
users_for_page = USERS[offset:offset + per_page]
total = len(USERS)
pagination = Pagination(
page=page, per_page=per_page, total=total,
css_framework='bootstrap4',
record_name='users'
)
# In a real app, you would have an 'index.html' template
# For this example, we'll return a minimal string.
# In your template, you would use: {{ pagination.render_macro('pagination.html') }}
return f"""<!doctype html>
<html lang='en'>
<head>
<meta charset='utf-8'>
<meta name='viewport' content='width=device-width, initial-scale=1, shrink-to-fit=no'>
<link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/bootstrap@4.6.2/dist/css/bootstrap.min.css' integrity='sha384-xOolHFLEh07PJGoPkLv1IbcEPTNtaed2xpHsD9ESMhqIYd0nLMwNLD69Npy4HI+N' crossorigin='anonymous'>
<title>Flask-Paginate Example</title>
</head>
<body>
<div class='container'>
<h1>Users</h1>
<ul>
{''.join([f'<li>User {user}</li>' for user in users_for_page])}
</ul>
<div class='text-center'>
{pagination.render_macro('pagination.html')}
</div>
</div>
</body>
</html>"""
if __name__ == '__main__':
app.run(debug=True)
Debug
Known issues
breakingThe `show_first_page_number` parameter in the `Pagination` constructor was renamed to `include_first_page_number`.fixUpdate your `Pagination` constructor calls to use `include_first_page_number` instead of `show_first_page_number`.
affects: < 2024.3.28
breakingOlder versions of `flask-paginate` (prior to 2023.10.8) are incompatible with Flask 3.0+ due to changes in how `Markup` is imported by Flask.fixUpgrade `flask-paginate` to version `2023.10.8` or newer to ensure compatibility with Flask 3.0 and above. This version internally updates the `Markup` import path.
affects: flask-paginate < 2023.10.8 (when used with Flask >= 3.0)
gotchaThe default CSS framework changed from Bootstrap 3 to Bootstrap 4.fixIf your templates are still based on Bootstrap 3 or you notice styling issues, explicitly set `css_framework='bootstrap3'` in the `Pagination` constructor, or update your templates to use Bootstrap 4/5 classes. `flask-paginate` also supports 'bootstrap5' directly.
affects: All versions from 2021.10.26 onwards
Errors
Common errors & fixes
TypeError: Pagination.__init__() got an unexpected keyword argument 'show_first_page_number'
You are using an outdated argument name for including the first page number in the pagination links.
fixReplace `show_first_page_number` with `include_first_page_number` in your `Pagination` constructor call.
ImportError: cannot import name 'Markup' from 'flask'
This error occurs when running an older version of `flask-paginate` (prior to 2023.10.8) with Flask 3.0 or newer. Flask 3 moved the `Markup` class from `flask` to `markupsafe`.
fixUpgrade `flask-paginate` to version `2023.10.8` or a newer version. `pip install --upgrade flask-paginate`.
Pagination links or styling appear broken after upgrading `flask-paginate` or `Flask`.
The default CSS framework for `flask-paginate` changed from Bootstrap 3 to Bootstrap 4 in version 2021.10.26. Your template HTML might be expecting Bootstrap 3.
fixExplicitly set `css_framework='bootstrap3'` in the `Pagination` constructor if you intend to use Bootstrap 3, or update your HTML templates to comply with Bootstrap 4 or 5 styling, then set `css_framework='bootstrap4'` or `css_framework='bootstrap5'` respectively.
Upgrade
Version history
2024.4.12latest on PyPI · released Apr 12, 2024
Audit
Dependencies
FlaskrequiredCore web framework integration.
MarkupSaferequiredFor HTML rendering, explicitly required for Flask 3+ compatibility.