---
title: "Paginator"
version: 4.0
locale: en
source: https://docs.djangoproject.com/en/4.0/ref/paginator/
canonical: https://djangodocs.dev/en/4.0/ref/paginator/
---
# 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](https://github.com/django/django/blob/stable/4.0.x/django/core/paginator.py).

For examples, see the [Pagination topic guide](/en/4.0/topics/pagination/).

## `Paginator` class

#### `class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)`

A paginator acts like a sequence of [`Page`](#django.core.paginator.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()`](/en/4.0/ref/models/querysets/#django.db.models.query.QuerySet.order_by) clause or with a default
[`ordering`](/en/4.0/ref/models/options/#django.db.models.Options.ordering) on the model.

> **Performance issues paginating large QuerySets**
>
> 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`](#django.core.paginator.Paginator.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.

#### `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.

### Methods

#### `Paginator.get_page(number)`

Returns a [`Page`](#django.core.paginator.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`](#django.core.paginator.EmptyPage) exception only if you specify
`Paginator(..., allow_empty_first_page=False)` and the `object_list` is
empty.

#### `Paginator.page(number)`

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

#### `Paginator.get_elided_page_range(number, * (Keyword-only parameters separator (PEP 3102)), on_each_side=3, on_ends=2)`

> **New in Django 3.2**

Returns a 1-based list of page numbers similar to
[`Paginator.page_range`](#django.core.paginator.Paginator.page_range), but may add an ellipsis to either or both
sides of the current page number when [`Paginator.num_pages`](#django.core.paginator.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`](#django.core.paginator.InvalidPage) if the given page number doesn’t exist.

### Attributes

#### `Paginator.ELLIPSIS`

> **New in Django 3.2**

A translatable string used as a substitute for elided page numbers in the
page range returned by [`get_elided_page_range()`](#django.core.paginator.Paginator.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]`.

## `Page` class

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

#### `class Page(object_list, number, paginator)`

A page acts like a sequence of [`Page.object_list`](#django.core.paginator.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`](#django.core.paginator.InvalidPage) if next page
doesn’t exist.

#### `Page.previous_page_number()`

Returns the previous page number. Raises [`InvalidPage`](#django.core.paginator.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()`](#django.core.paginator.Page.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()`](#django.core.paginator.Page.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`](#django.core.paginator.Paginator) object.

## Exceptions

#### `exception InvalidPage`

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

The [`Paginator.page()`](#django.core.paginator.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()`](#django.core.paginator.Paginator.page) is given a value that isn’t an integer.

#### `exception EmptyPage`

Raised when [`page()`](#django.core.paginator.Paginator.page) is given a valid value but no objects
exist on that page.

Both of the exceptions are subclasses of [`InvalidPage`](#django.core.paginator.InvalidPage), so you can handle
them both with `except InvalidPage`.