Skip to content

Effortlessly Sort Data with heapq in Python


The Python heapq Module: Using Heaps and Priority Queues

Heaps and priority queues are powerful data structures that can solve a variety of problems. The Python heapq module, part of the standard library, provides all the necessary operations to work with heaps effectively. In this tutorial, we will explore what heaps and priority queues are, how they relate to each other, and how to use the heapq module to solve problems efficiently.

What Are Heaps?

Heaps are concrete data structures commonly used to implement priority queues, which are abstract data structures. An abstract data structure defines the interface, while a concrete data structure provides the implementation details. In the case of heaps and priority queues, heaps are the concrete implementation of the priority queue abstract data structure.

Heaps offer performance guarantees, which specify the relationship between the size of the data structure and the time it takes to perform operations. Understanding these guarantees allows us to estimate the time complexity of our programs as the input size changes.

Data Structures, Heaps, and Priority Queues

The priority queue abstract data structure supports three main operations: is_empty, add_element, and pop_element. It is commonly used for optimizing task execution based on priority. Tasks with higher priority are executed first, and after completion, their priority is lowered, and they are returned to the queue.

The priority of an element in a priority queue can be determined in two ways: the largest element has the highest priority or the smallest element has the highest priority. The heapq module in Python follows the convention of having the smallest element with the highest priority.

Heaps as Lists in the Python heapq Module

The Python heapq module provides a function called heappush that can be used to add elements to a heap. The heap itself is represented as a list, where the first element is always the smallest. The heappop function can be used to remove and return the smallest element from the heap.

The heapify function in the heapq module can be used to convert a regular list into a heap. This is useful when we already have a list of elements and want to use it as a heap.

Basic Operations

To demonstrate the basic operations of heaps in the heapq module, consider the following example:

import heapq
# Create an empty heap
heap = []
# Add elements to the heap
heapq.heappush(heap, 4)
heapq.heappush(heap, 1)
heapq.heappush(heap, 7)
heapq.heappush(heap, 3)
# Remove and retrieve the smallest element
smallest = heapq.heappop(heap)
print(smallest) # Output: 1

In this example, we create an empty heap and use heappush to add elements to it. The heappop function is then used to remove and retrieve the smallest element from the heap. The output of this code will be 1.

A High-Level Operation

The nsmallest function in the heapq module can be used to retrieve the n smallest elements from a heap. This function returns a list containing the smallest elements in ascending order.

import heapq
# Create a heap with multiple elements
heap = [5, 8, 2, 1, 6, 3, 9, 4]
# Retrieve the 3 smallest elements
smallest_elements = heapq.nsmallest(3, heap)
print(smallest_elements) # Output: [1, 2, 3]

In this example, we have a heap represented as a list of numbers. The nsmallest function is used to retrieve the 3 smallest elements from the heap. The output of this code will be [1, 2, 3].

Problems Heaps Can Solve

Heaps are particularly useful when solving problems that involve finding the best element in a dataset. Some examples of problems that can be solved using heaps include finding the smallest or largest elements, finding the n smallest or largest elements, and performing efficient sorting.

How to Identify Problems

When faced with a problem, consider whether finding the best element is a key requirement. If it is, a heap might be a suitable data structure to solve the problem efficiently.

Example: Finding Paths

To illustrate the usage of heaps in solving problems, let’s consider an example of finding paths in a graph. We will use a priority queue, implemented as a heap, to efficiently find the shortest path from a starting node to a target node.

The code for this example consists of several parts: top-level code, support code, core algorithm code, and visualization code. Running the code will allow us to see the discovered paths and how the algorithm works.


In this tutorial, we have explored the Python heapq module and its usage in working with heaps and priority queues. We have learned what heaps are, how they relate to priority queues, and the basic operations provided by the heapq module. Heaps are powerful data structures that can significantly simplify and optimize many programming problems.