Python Django Pagination: Paginator and ListView
Learn Python Django pagination with Paginator and ListView, including template controls, invalid page handling, and performance notes.

When a Django view returns a large QuerySet, rendering every row in a single template response becomes slow and unwieldy. The standard solution is Django's pagination utilities, which split results into pages. Django provides two primary tools: the Paginator class for function-based views and the paginate_by attribute on ListView for class-based views. Both rely on the same underlying mechanism and produce a Page object that templates can iterate over.
Understanding Django's Paginator Class
The Paginator class lives in django.core.paginator. It takes an object list—typically a QuerySet—and a page size, then exposes methods to retrieve specific pages. For a QuerySet, it does not load all objects into memory at once. When the total number of pages is needed, it runs a COUNT query; the page query then uses LIMIT and OFFSET clauses to fetch only the rows for the requested page.
from django.core.paginator import Paginator
items = Item.objects.all()
paginator = Paginator(items, 10) # 10 items per page
page_number = request.GET.get('page')
page_obj = paginator.get_page(page_number)get_page() handles invalid page numbers gracefully. If the page is not an integer, it returns the first page. If the page is out of range, it returns the last page. This is convenient for user-facing views where you do not want to raise a 404 for a malformed query parameter.
Paginating a QuerySet in a Function-Based View
In a function-based view, you create a Paginator from the QuerySet, retrieve the current page, and pass it to the template context. The view must read the page query parameter and pass it to get_page().
from django.shortcuts import render
from django.core.paginator import Paginator
from .models import Item
def item_list(request):
items = Item.objects.all().order_by('-created_at')
paginator = Paginator(items, 20)
page_number = request.GET.get('page')
page_obj = paginator.get_page(page_number)
return render(request, 'items/item_list.html', {'page_obj': page_obj})The page_obj is a Page instance. It has .object_list containing the items for the current page, and it exposes methods such as has_previous(), has_next(), previous_page_number(), and next_page_number(). In Django templates, method calls are automatic, so page_obj.has_previous and page_obj.previous_page_number work without parentheses.
Using ListView with paginate_by
Class-based views reduce boilerplate. ListView has a paginate_by attribute that automatically paginates the queryset. You only need to set the attribute and provide a template context variable name.
from django.views.generic import ListView
from .models import Item
class ItemListView(ListView):
model = Item
template_name = 'items/item_list.html'
context_object_name = 'items'
paginate_by = 20By default, ListView passes a page_obj to the template, just like the function-based view. The paginate_by attribute triggers the same Paginator logic internally. You can override get_queryset() to filter or order the objects, and the pagination will apply to the resulting QuerySet.
Rendering Pagination Controls in Templates
The template receives page_obj. A common pattern is to display the current page's items and then render a set of page links. Django's template language does not have a built-in pagination widget, so you build the controls manually.
{% for item in page_obj %}
<div class="item">{{ item.name }}</div>
{% endfor %}
<div class="pagination">
{% if page_obj.has_previous %}
<a href="?page={{ page_obj.previous_page_number }}">Previous</a>
{% endif %}
<span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}</span>
{% if page_obj.has_next %}
<a href="?page={{ page_obj.next_page_number }}">Next</a>
{% endif %}
</div>This basic control works, but it only shows previous and next links. For a more complete pagination bar with page numbers, you can iterate over page_obj.paginator.page_range. The page_range is a range object from 1 to num_pages. You can conditionally highlight the current page.
{% for num in page_obj.paginator.page_range %}
{% if num == page_obj.number %}
<span class="current">{{ num }}</span>
{% else %}
<a href="?page={{ num }}">{{ num }}</a>
{% endif %}
{% endfor %}Be careful with very large page counts. Rendering every page number can produce a huge list. Many sites use an ellipsis pattern, but that requires custom template logic or a template filter.
Handling Invalid Page Numbers and Empty Pages
get_page() in a function-based view is lenient, but ListView is stricter. If the page number is not an integer or is out of range, ListView raises Http404. If you want the same fallback behavior as get_page(), you can override get() or paginate_queryset() in your ListView.
For empty pages—when a page exists but has no objects because the queryset is empty—get_page() returns an empty Page object. The template should handle that case by checking page_obj.object_list. With ListView's default allow_empty = True, an empty queryset still produces a page with no items, and the template must not assume there is at least one object.
To display the total number of items, use page_obj.paginator.count. Accessing count or paginator.num_pages runs the COUNT query needed to build navigation controls, so this is normally not an unnecessary query when you show a full pagination bar. Do not call len() on the unrestricted QuerySet to get the total; that would load the entire result set. len(page_obj.object_list) reports only the number of items on the current page.
Performance Considerations for Large QuerySets
Paginating a QuerySet is efficient because Django does not load the full result set. In a typical page request, the paginator runs a COUNT query to learn the total number of pages and a SELECT with LIMIT and OFFSET to load only the rows for the requested page. The COUNT query is fast if the database has an appropriate index on the filtered columns. The OFFSET approach can become slower as the page number increases, because the database still has to scan and discard earlier rows. For very deep pagination, consider keyset pagination (also called the 'seek method') using WHERE id > last_id instead of OFFSET. Django does not provide this out of the box, but you can implement it manually.
Another performance concern is ordering. The QuerySet passed to the Paginator must have a deterministic order. If you do not call order_by(), the database may return rows in an unpredictable order, and pagination will appear inconsistent across requests. Always add an explicit ordering, either in the model's Meta class or in the view's get_queryset().
Custom Pagination and Alternative Approaches
While the built-in Paginator covers most needs, some applications require custom behavior. For example, you might want to paginate by a cursor instead of a page number, or you might need to combine pagination with filtering. Django's Paginator works with any iterable, but it is optimized for QuerySets. If you need to paginate a list that is already in memory, you can pass the list directly, but the COUNT operation will be a Python len() call, and slicing will be done in memory.
If you want stricter page-number validation than get_page() provides, validate the page number in your view before calling page(). This gives you a clear place to raise a 404 for bad page values.
from django.core.paginator import Paginator
from django.http import Http404
items = Item.objects.all().order_by('-created_at')
paginator = Paginator(items, 20)
page_number = request.GET.get('page', '1')
try:
page_number = int(page_number)
except (TypeError, ValueError):
raise Http404('Invalid page number')
if page_number < 1 or page_number > paginator.num_pages:
raise Http404('Page out of range')
page_obj = paginator.page(page_number)The choice between function-based and class-based views for pagination often comes down to team preference and the complexity of the view. For simple list pages, ListView is concise. For views that need custom query handling or multiple paginated sections, a function-based view with explicit Paginator usage gives you more direct control. Both approaches produce the same Page object, so the template code remains identical.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.