Comprehensive Introduction and Usage Guide for PyMuPDF (Python Bindings for MuPDF)

1. PyMuPDF Introduction

Before introducing PyMuPDF , it is helpful to understand MuPDF , which is the underlying lightweight PDF, XPS, and e‑book viewer library. MuPDF consists of a core library, command‑line tools, and platform viewers, offering high‑quality anti‑aliased rendering, precise text layout, and fast performance while supporting many document formats such as PDF, XPS, OpenXPS, CBZ, EPUB, and FictionBook 2.

The command‑line utilities allow annotation, editing, and conversion to formats like HTML, SVG, PDF, and CBZ, and a Javascript interface enables scripting.

2. Features

Decrypt files, access metadata, links, bookmarks; render pages as raster ( PNG ) or vector ( SVG ) images; search text; extract text and images; convert to other formats (PDF, (X)HTML, XML, JSON, plain text).

For PDF documents, additional capabilities include creating, merging, splitting pages; inserting, deleting, rearranging, or modifying pages (including annotations and form fields); extracting or inserting images and fonts; full support for embedded files; reformatting for duplex printing, spot colors, watermarks; comprehensive password protection and encryption options; and low‑level PDF structure manipulation.

Command‑line module python -m fitz … provides encryption/decryption, optimization, sub‑document creation, document concatenation, image/font extraction, and layout‑preserving text extraction via the fitzcliy.py script.

3. Installation

PyMuPDF can be installed from source or via pre‑built wheels on PyPI. Wheels are available for 64‑bit Python 3.6‑3.9 on Windows, Linux, and macOS, with additional manylinux2014_aarch64 wheels for ARM platforms.

Optional dependencies:

Pillow – required for Pixmap.pil_save() and Pixmap.pil_tobytes() .

fontTools – required for Document.subset_fonts() .

pymupdf‑fonts – provides a collection of fonts for text output.

Typical installation command:

<code>pip install PyMuPDF</code>

4. Importing the Library

<code>import fitz</code>

The import name fitz originates from the historic name of the MuPDF rendering engine.

5. Basic Usage

5.1 Import and Version

<code>import fitz
print(fitz.__doc__)
# Example output:
# PyMuPDF 1.18.16: Python bindings for the MuPDF 1.18.0 library.
# Version date: 2021‑08‑05 00:00:01.
# Built for Python 3.8 on linux (64‑bit).
</code>

5.2 Opening a Document

<code>doc = fitz.open(filename)  # filename is a path string or a bytes object</code>

This creates a Document object. Documents can also be opened from memory or created as empty PDFs, and can be used as context managers.

5.3 Document Methods and Properties

Method/Property

Description

Document.page_count

Number of pages (int)

Document.metadata

Metadata dictionary

Document.get_toc()

Table of contents (list)

Document.load_page()

Load a specific page

<code># Example usage
>>> doc.page_count
1
>>> doc.metadata
{'format': 'PDF 1.7', 'title': '', 'author': '', ...}
</code>

5.4 Accessing Pages

<code>page = doc.load_page(pno)   # 0‑based page number
# or short form
page = doc[pno]
</code>

Pages can be accessed with negative indices (e.g., doc[-1] for the last page) and iterated directly:

<code>for page in doc:
    # process page
    pass

for page in reversed(doc):
    # process pages backwards
    pass

for page in doc.pages(start, stop, step):
    # sliced iteration
    pass
</code>

5.5 Page Operations

Links, Annotations, Form Fields : links = page.get_links() returns a list of dictionaries; for annot in page.annots(): ... iterates annotations; for field in page.widgets(): ... iterates form fields.

Rendering : pix = page.get_pixmap() creates a raster Pixmap (default RGB). Options allow alpha channel, different resolutions, color spaces, rotation, cropping, etc. Example: pix = page.get_pixmap(alpha=True) .

Saving Rendered Images : pix.save("page-%i.png" % page.number) .

Extracting Text : text = page.get_text(opt) where opt can be "text", "blocks", "words", "html", "dict", "json", "rawdict", "rawjson", "xhtml", "xml", or "svg" to obtain different representations.

Searching Text : areas = page.search_for("mupdf") returns a list of rectangles for each match.

6. PDF‑Specific Operations

Only PDF documents can be modified with PyMuPDF . Other formats are read‑only, but any document can be converted to PDF via Document.convert_to_pdf() .

Document.delete_page() / delete_pages() – remove pages.

Document.copy_page() , fullcopy_page() , move_page() – duplicate or move pages within the same document.

Document.select() – create a new PDF containing only selected pages.

Document.insert_page() / new_page() – insert a new blank page.

Document.insert_pdf() – concatenate pages from another PDF. <code># Append doc2 to the end of doc1 doc1.insert_pdf(doc2) </code>

Splitting example (first 10 pages and last 10 pages): <code>doc2 = fitz.open() # new empty PDF doc2.insert_pdf(doc1, to_page=9) # first 10 pages doc2.insert_pdf(doc1, from_page=len(doc1)-10) # last 10 pages doc2.save("first-and-last-10.pdf") </code>

Document.save(incremental=True) – write changes back to the original file quickly by appending.

Document.close() – release file handles and buffers.

7. Additional Resources

For further reading, see the recommended articles linked at the end of the original post.