DisplayList is a list containing drawing commands (text, images, etc.). The intent is two-fold:

  1. as a caching-mechanism to reduce parsing of a page
  2. as a data structure in multi-threading setups, where one thread parses the page and another one renders pages. This aspect is currently not supported by PyMuPDF.

A display list is populated with objects from a page, usually by executing Page.get_displaylist(). There also exists an independent constructor.

“Replay” the list (once or many times) by invoking one of its methods run(), get_pixmap() or get_textpage().

Method Short Description
run() Run a display list through a device.
get_pixmap() generate a pixmap
get_textpage() generate a text page
rect mediabox of the display list

Class API

class DisplayList
__init__(self, mediabox)

Create a new display list.

Parameters:mediabox (Rect) – The page’s rectangle.
Return type:DisplayList
run(device, matrix, area)

Run the display list through a device. The device will populate the display list with its “commands” (i.e. text extraction or image creation). The display list can later be used to “read” a page many times without having to re-interpret it from the document file.

You will most probably instead use one of the specialized run methods below – get_pixmap() or get_textpage().

  • device (Device) – Device
  • matrix (Matrix) – Transformation matrix to apply to the display list contents.
  • area (Rect) – Only the part visible within this area will be considered when the list is run through the device.
get_pixmap(matrix=fitz.Identity, colorspace=fitz.csRGB, alpha=0, clip=None)

Run the display list through a draw device and return a pixmap.

  • matrix (Matrix) – matrix to use. Default is the identity matrix.
  • colorspace (Colorspace) – the desired colorspace. Default is RGB.
  • alpha (int) – determine whether or not (0, default) to include a transparency channel.
  • clip (irect_like) – restrict rendering to the intersection of this area with DisplayList.rect.
Return type:



pixmap of the display list.


Run the display list through a text device and return a text page.

Parameters:flags (int) – control which information is parsed into a text page. Default value in PyMuPDF is 3 = TEXT_PRESERVE_LIGATURES | TEXT_PRESERVE_WHITESPACE, i.e. ligatures are passed through, white spaces are passed through (not translated to spaces), and images are not included. See Text Extraction Flags.
Return type:TextPage
Returns:text page of the display list.

Contains the display list’s mediabox. This will equal the page’s rectangle if it was created via Page.get_displaylist().