# Django 5.2.7 documentation

# Paginator

Django provides a few classes that help you manage paginated data – that is, data that’s split across several pages, with “Previous/Next” links. These classes live in django/core/paginator.py.

For examples, see the Pagination topic guide.

## `Paginator` class

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)

  A paginator acts like a sequence of `Page` when using `len()` or iterating it directly.

Paginator.object_list

  Required. A list, tuple, `QuerySet`, or other sliceable object with a `count()` or `__len__()` method. For consistent pagination, `QuerySet`s should be ordered, e.g. with an `order_by()` clause or with a default `ordering` on the model.

  Performance issues paginating large `QuerySet`s

  If you’re using a `QuerySet` with a very large number of items, requesting high page numbers might be slow on some databases, because the resulting `LIMIT`/`OFFSET` query needs to count the number of `OFFSET` records which takes longer as the page number gets higher.

Paginator.per_page

  Required. The maximum number of items to include on a page, not including orphans (see the `orphans` optional argument below).

Paginator.orphans

  Optional. Use this when you don’t want to have a last page with very few items. If the last page would normally have a number of items less than or equal to `orphans`, then those items will be added to the previous page (which becomes the last page) instead of leaving the items on a page by themselves. For example, with 23 items, `per_page=10`, and `orphans=3`, there will be two pages; the first page with 10 items and the second (and last) page with 13 items. `orphans` defaults to zero, which means pages are never combined and the last page may have one item. `orphans` should be less than the `per_page` value.

  Deprecated since version 6.0: Support for the `orphans` argument being larger than or equal to the `per_page` argument is deprecated.

Paginator.allow_empty_first_page

  Optional. Whether or not the first page is allowed to be empty. If `False` and `object_list` is empty, then an `EmptyPage` error will be raised.

Paginator.error_messages

  The `error_messages` argument lets you override the default messages that the paginator will raise. Pass in a dictionary with keys matching the error messages you want to override. Available error message keys are: `invalid_page`, `min_page`, and `no_results`.

  For example, here is the default error message:

      >>> from django.core.paginator import Paginator
      >>> paginator = Paginator([1, 2, 3], 2)
      >>> paginator.page(5)
      Traceback (most recent call last):
        ...
      EmptyPage: That page contains no results

  And here is a custom error message:

      >>> paginator = Paginator(
      ...     [1, 2, 3],
      ...     2,
      ...     error_messages={"no_results": "Page does not exist"},
      ... )
      >>> paginator.page(5)
      Traceback (most recent call last):
        ...
      EmptyPage: Page does not exist

### Methods

Paginator.get_page(number)

  Returns a `Page` object with the given 1-based index, while also handling out of range and invalid page numbers.

  If the page isn’t a number, it returns the first page. If the page number is negative or greater than the number of pages, it returns the last page.

  Raises an `EmptyPage` exception only if you specify `Paginator(..., allow_empty_first_page=False)` and the `object_list` is empty.

Paginator.page(number)

  Returns a `Page` object with the given 1-based index. Raises `PageNotAnInteger` if the `number` cannot be converted to an integer by calling `int()`. Raises `EmptyPage` if the given page number doesn’t exist.

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)

  Returns a 1-based list of page numbers similar to `Paginator.page_range`, but may add an ellipsis to either or both sides of the current page number when `Paginator.num_pages` is large.

  The number of pages to include on each side of the current page number is determined by the `on_each_side` argument which defaults to 3.

  The number of pages to include at the beginning and end of page range is determined by the `on_ends` argument which defaults to 2.

  For example, with the default values for `on_each_side` and `on_ends`, if the current page is 10 and there are 50 pages, the page range will be `[1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]`. This will result in pages 7, 8, and 9 to the left of and 11, 12, and 13 to the right of the current page as well as pages 1 and 2 at the start and 49 and 50 at the end.

  Raises `InvalidPage` if the given page number doesn’t exist.

### Attributes

Paginator.ELLIPSIS

  A translatable string used as a substitute for elided page numbers in the page range returned by `get_elided_page_range()`. Default is `'…'`.

Paginator.count

  The total number of objects, across all pages.

  Note

  When determining the number of objects contained in `object_list`, `Paginator` will first try calling `object_list.count()`. If `object_list` has no `count()` method, then `Paginator` will fall back to using `len(object_list)`. This allows objects, such as `QuerySet`, to use a more efficient `count()` method when available.

Paginator.num_pages

  The total number of pages.

Paginator.page_range

  A 1-based range iterator of page numbers, e.g. yielding `[1, 2, 3, 4]`.

## `AsyncPaginator` class

New in Django 6.0.

class AsyncPaginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)

  Asynchronous version of `Paginator`.

  `AsyncPaginator` has the same attributes and signatures as `Paginator`, with the following exceptions:

  - The attribute `Paginator.count` is supported as an asynchronous method `AsyncPaginator.acount()`.

  - The attribute `Paginator.num_pages` is supported as an asynchronous method `AsyncPaginator.anum_pages()`.

  - The attribute `Paginator.page_range` is supported as an asynchronous method `AsyncPaginator.apage_range()`.

  `AsyncPaginator` has asynchronous versions of the same methods as `Paginator`, using an `a` prefix - for example, use `await async_paginator.aget_page(number)` rather than `paginator.get_page(number)`.

## `Page` class

You usually won’t construct `Page` objects by hand – you’ll get them by iterating `Paginator`, or by using `Paginator.page()`.

class Page(object_list, number, paginator)

  A page acts like a sequence of `Page.object_list` when using `len()` or iterating it directly.

### Methods

Page.has_next()

  Returns `True` if there’s a next page.

Page.has_previous()

  Returns `True` if there’s a previous page.

Page.has_other_pages()

  Returns `True` if there’s a next or previous page.

Page.next_page_number()

  Returns the next page number. Raises `InvalidPage` if next page doesn’t exist.

Page.previous_page_number()

  Returns the previous page number. Raises `InvalidPage` if previous page doesn’t exist.

Page.start_index()

  Returns the 1-based index of the first object on the page, relative to all of the objects in the paginator’s list. For example, when paginating a list of 5 objects with 2 objects per page, the second page’s `start_index()` would return `3`.

Page.end_index()

  Returns the 1-based index of the last object on the page, relative to all of the objects in the paginator’s list. For example, when paginating a list of 5 objects with 2 objects per page, the second page’s `end_index()` would return `4`.

### Attributes

Page.object_list

  The list of objects on this page.

Page.number

  The 1-based page number for this page.

Page.paginator

  The associated `Paginator` object.

## `AsyncPage` class

New in Django 6.0.

class AsyncPage(object_list, number, paginator)

  Asynchronous version of `Page`.

  `AsyncPage` has the same attributes and signatures as `Page`, as well as asynchronous versions of all the same methods, using an `a` prefix - for example, use `await async_page.ahas_next()` rather than `page.has_next()`.

  `AsyncPage` has the following additional method:

  aget_object_list()

    Returns `AsyncPage.object_list` as a list. This method must be awaited before `AsyncPage` can be treated as a sequence of `AsyncPage.object_list`.

## Exceptions

exception InvalidPage

  A base class for exceptions raised when a paginator is passed an invalid page number.

The `Paginator.page()` method raises an exception if the requested page is invalid (i.e. not an integer) or contains no objects. Generally, it’s enough to catch the `InvalidPage` exception, but if you’d like more granularity, you can catch either of the following exceptions:

exception PageNotAnInteger

  Raised when `page()` is given a value that isn’t an integer.

exception EmptyPage

  Raised when `page()` is given a valid value but no objects exist on that page.

Both of the exceptions are subclasses of `InvalidPage`, so you can handle them both with `except InvalidPage`.