Migrating from PyMuPDF

pdfspine is designed so that existing PyMuPDF code can run unmodified for the supported subset. This page is the honest, no-marketing account of what works, what differs, and what isn't there yet.

import fitz — one opt-in step

The compatibility shim maps PyMuPDF's exact names onto pdfspine. It is opt-in so a default install never collides with a real PyMuPDF in the same environment. Either import the shim under its submodule name (no global-name collision):

import pdfspine.fitz as fitz      # the shim, always available

doc = fitz.open("input.pdf")
page = doc[0]
text = page.get_text()
pix = page.get_pixmap(dpi=150)
pix.save("out.png")
doc.save("out.pdf")

…or, to keep an unmodified import fitz working, opt in once at startup:

import pdfspine
pdfspine.install_fitz_shim()      # registers global `fitz` / `pymupdf`
import fitz                       # now resolves to the pdfspine shim

install_fitz_shim() is idempotent and uses setdefault, so it never clobbers a real PyMuPDF you already imported. import pymupdf (and from pdfspine import pymupdf) is supported the same way. For new code, prefer the native package:

import pdfspine
doc = pdfspine.open("input.pdf")

Both expose the identical open, Document, Page, Pixmap, DisplayList, TextPage, Annot, Widget, Shape, Table, and geometry classes.

Coverage at a glance

The baseline is PyMuPDF 1.24.x. The machine-readable COMPAT.toml in the repository tracks the disposition of every public PyMuPDF symbol:

How gaps behave

Anything not yet implemented raises a typed, catchable pdfspine.PdfUnsupportedError (aliased as fitz.PdfUnsupportedError) with a hint — never a bare AttributeError. That means you can detect and handle gaps cleanly:

import pdfspine

try:
    doc.some_unimplemented_method()
except pdfspine.PdfUnsupportedError as e:
    print("not yet:", e)

PyMuPDF exception names are aliased onto the typed hierarchy, so existing except clauses keep working:

What is 100% compatible

The geometry layer (Point, Rect, IRect, Matrix, Quad) mirrors PyMuPDF 1.24.x arithmetic exactly — operators, transforms, inversion, morph / torect, quad convexity — as a documented contract. These classes are also sequences, so r[0], tuple(r), and unpacking all behave like PyMuPDF.

Feature mapping

What differs

• scrub toggles — the full PyMuPDF toggle set is accepted, but only a subset (metadata, JavaScript, attached/embedded files, links, XMP) is acted on; the rest are no-ops.
• insert_image(pixmap=...) — not yet supported; pass stream= bytes or filename= instead.
• Deprecated camelCase aliases — PyMuPDF's old getText / getPixmap / setMetadata style names are provided as aliases where they existed, so legacy code keeps working.
• to_html() on tables — an pdfspine extra beyond PyMuPDF.

What is not yet implemented

These are the 21 deferred (planned) symbols — they raise PdfUnsupportedError today:

• OCG / layer-config nesting — add_layer, get_layers, switch_layer, set_layer_ui_config, get_oc, get_ocmd, set_ocmd (the basic get_ocgs / set_layer / set_oc read+toggle+bind surface works today).
• Low-level text writing — Page.write_text, Page.insert_font (the higher-level insert_text / insert_textbox / TextWriter work today).
• Device-callback replay — Page.run, DisplayList.run, DisplayList.get_textpage (get_pixmap covers the raster path).
• Misc Page helpers — remove_rotation, refresh, extend_textpage.
• Pixmap.warp, Annot.get_textbox, Document.insert_file (non-image attachments; image inputs to open are supported), Document.FormFonts.
• Tools.set_annot_stem, Tools.set_subset_fontnames.

Out of scope for v1

Intentionally never in v1 (these raise PdfUnsupportedError):

• EPUB-class reflow (doc.layout, next_location / prev_location, make_bookmark / find_bookmark).
• HTML/CSS layout (Story, insert_htmlbox, Xml, Archive).
• Journalling op-naming / persistence (journal_start_op, journal_stop_op, journal_op_name, journal_position, journal_save, journal_load, save_snapshot) — the basic journal_enable / journal_undo / journal_redo / journal_can_do surface is implemented.
• Full Unicode shaping (complex scripts).

get_textpage_ocr and the pdfocr_* sandwich-PDF export are implemented, not out of scope — see Rendering and the OCR benchmark.

Consult the repository's COMPAT.toml for the authoritative, per-symbol disposition — it is CI-enforced to stay in sync with the code.