API Reference

sopdf.open(
    path: str | pathlib.Path | None = None,
    password: str | None = None,
    *,
    stream: bytes | None = None,
) -> Document

# Open from a file path
doc = sopdf.open("report.pdf")

# Open an encrypted document
doc = sopdf.open("secure.pdf", password="hunter2")

# Open from raw bytes in memory
with open("report.pdf", "rb") as f:
    doc = sopdf.open(stream=f.read())

# Recommended: use a context manager for automatic resource cleanup
with sopdf.open("report.pdf") as doc:
    print(doc.page_count)

sopdf.merge(
    inputs: list[str | pathlib.Path],
    output: str | pathlib.Path,
) -> None

sopdf.merge(
    ["intro.pdf", "body.pdf", "appendix.pdf"],
    output="book.pdf",
)

sopdf.render_pages(
    pages: list[Page],
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
    parallel: bool = False,
) -> list[bytes]

with sopdf.open("report.pdf") as doc:
    # Sequential rendering
    images = sopdf.render_pages(doc.pages, dpi=150)

    # Parallel rendering with multiprocessing (recommended for large documents)
    images = sopdf.render_pages(doc.pages, dpi=300, parallel=True)

sopdf.render_pages_to_files(
    pages: list[Page],
    output_dir: str | pathlib.Path,
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
    parallel: bool = False,
) -> None

with sopdf.open("report.pdf") as doc:
    sopdf.render_pages_to_files(doc.pages, "output/", dpi=150, parallel=True)
# Produces: output/page_0.png, output/page_1.png, ...

doc.page_count -> int

len(doc) -> int

doc.metadata -> Metadata

# Read
print(doc.metadata.title)
print(doc.metadata.creation_datetime)  # Python datetime

# Write (lazily initialises pikepdf, marks document dirty)
doc.metadata.title  = "Annual Report 2025"
doc.metadata.author = "Kevin Qiu"
doc.save("updated.pdf")

doc.outline -> Outline

for item in doc.outline.items:
    print(f"[p{item.page + 1}] {item.title}")

flat = doc.outline.to_list()  # PyMuPDF-compatible flat list

doc.is_encrypted -> bool

doc.pages -> _PageList

doc[index: int] -> Page
doc.load_page(index: int) -> Page

first_page = doc[0]
last_page  = doc[-1]
third_page = doc.load_page(2)

for page in doc:
    print(page.number)

doc.split(
    pages: list[int],
    output: str | pathlib.Path | None = None,
) -> Document

# Extract the first 3 pages and save to disk
chapter = doc.split(pages=[0, 1, 2], output="chapter1.pdf")

# Extract to memory only, no disk write
excerpt = doc.split(pages=[4, 5, 6])

doc.split_each(output_dir: str | pathlib.Path) -> None

doc.split_each("pages/")
# Produces: pages/page_0.pdf, pages/page_1.pdf, ...

doc.append(other: Document) -> None

with sopdf.open("part1.pdf") as doc_a, sopdf.open("part2.pdf") as doc_b:
    doc_a.append(doc_b)
    doc_a.save("combined.pdf")

doc.save(
    path: str | pathlib.Path,
    *,
    compress: bool = True,
    garbage: bool = False,
    linearize: bool = False,
) -> None

# Basic save (compression enabled by default)
doc.save("output.pdf")

# Maximum compression
doc.save("output.pdf", compress=True, garbage=True)

# Strip encryption (open with the correct password, then save)
doc.save("unlocked.pdf")

doc.to_bytes(compress: bool = True) -> bytes

pdf_bytes = doc.to_bytes()

# Return directly as a Flask HTTP response
from flask import Response
return Response(doc.to_bytes(), mimetype="application/pdf")

doc.close() -> None

with sopdf.open("file.pdf") as doc:
    ...
# close() is called automatically on exit

page.number -> int

page.rect -> Rect

page.rotation -> int          # read current rotation
page.rotation = degrees: int  # set rotation

page.render(
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
) -> bytes

png_bytes  = page.render(dpi=150)
jpeg_bytes = page.render(dpi=150, format="jpeg")
png_alpha  = page.render(dpi=72, alpha=True)

page.render_to_file(
    path: str | pathlib.Path,
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
) -> None

page.render_to_file("page0.png", dpi=300)
page.render_to_file("page0.jpg", dpi=150, format="jpeg")

page.get_text(
    *,
    rect: Rect | None = None,
) -> str

full_text = page.get_text()

# Extract from a specific region only
region = Rect(0, 0, 300, 100)
header_text = page.get_text(rect=region)

page.get_text_blocks(
    *,
    rect: Rect | None = None,
    format: str = "list",
) -> list

blocks = page.get_text_blocks()
for block in blocks:
    print(block.text, block.rect)

# Return as dictionaries (convenient for JSON serialization)
dicts = page.get_text_blocks(format="dict")

page.search(
    query: str,
    *,
    match_case: bool = False,
) -> list[Rect]

hits = page.search("invoice")
for rect in hits:
    print(f"Match at {rect}")

# Case-sensitive search
hits = page.search("PDF", match_case=True)

page.search_text_blocks(
    query: str,
    *,
    match_case: bool = False,
) -> list[dict]

results = page.search_text_blocks("total amount")
for r in results:
    print(r["text"])        # full paragraph containing the keyword
    print(r["match_rect"])  # exact position of the keyword

Rect(x0: float, y0: float, x1: float, y1: float)

r = Rect(10, 20, 200, 300)
print(r.width)    # 190.0
print(r.height)   # 280.0

# Containment check
print(r.contains(Rect(50, 50, 100, 100)))  # True
print(r.contains((50, 50)))                # True (point)

# Intersection
a = Rect(0, 0, 100, 100)
b = Rect(50, 50, 150, 150)
print(a.intersect(b))  # Rect(50, 50, 100, 100)

# Unpack
x0, y0, x1, y1 = r

TextBlock(text: str, rect: Rect)

blocks = page.get_text_blocks()
for block in blocks:
    print(block.text)
    print(block.rect.width, block.rect.height)
    print(block.to_dict())

with sopdf.open("report.pdf") as doc:
    meta = doc.metadata

    # Read individual fields
    print(meta.title)
    print(meta.creation_datetime)   # datetime(2024, 1, 1, 12, 0, tzinfo=...)

    # Write
    meta.title  = "New Title"
    meta.author = "Kevin Qiu"
    doc.save("updated.pdf")

    # Dict-style read (backward compat)
    d = meta.to_dict()
    print(d["title"])
    print(meta["author"])

@dataclass(frozen=True)
class OutlineItem:
    title:    str
    page:     int                          # 0-based; -1 = no destination page
    level:    int                          # 0 = top-level
    children: tuple[OutlineItem, ...] = ()

with sopdf.open("textbook.pdf") as doc:
    outline = doc.outline
    print(outline)          # Outline(top_level=2, total=4)
    print(bool(outline))    # True

    # Recursive tree traversal
    def print_tree(items, indent=0):
        for item in items:
            print("  " * indent + f"[p{item.page + 1}] {item.title}")
            print_tree(item.children, indent + 1)

    print_tree(outline.items)

    # Flat list (PyMuPDF-compatible)
    for row in outline.to_list():
        print(f"{'  ' * row['level']}{row['title']}  →  p{row['page'] + 1}")

RuntimeError
└── PDFError
    ├── PasswordError
    ├── FileDataError
    └── PageError

import sopdf

try:
    doc = sopdf.open("file.pdf", password="wrong")
except sopdf.PasswordError:
    print("Incorrect password")
except sopdf.FileDataError:
    print("File is corrupted")
except sopdf.PDFError as e:
    print(f"PDF error: {e}")