oxpdf

High-performance, streaming PDF engine for Python — powered by Rust 🦀

oxpdf provides blazing-fast, memory-bounded, layout-aware PDF processing for Python. Built from the ground up in Rust with zero heavy C/C++ dependencies, oxpdf delivers orders-of-magnitude faster parsing and Markdown conversion than legacy Python libraries (pypdf, pdfplumber, pdfminer.six).

Key Features

• ⚡ Blazing Fast: SIMD/SWAR-accelerated tokenization, streaming parser.
• 📐 Layout-Aware Markdown: Recursive XY-Cut algorithm for accurate multi-column reading order.
• 📊 Table Reconstruction: Geometric table recovery into clean GitHub-Flavored Markdown tables.
• 🖼️ Zero-Copy Image Extraction: Direct JPEG stream dumps from DCTDecode and PNG synthesis from Flate streams.
• 🛡️ Memory-Bounded & Safe: Protected against cyclic references, decompression bombs, and OOM.
• 🔒 PDF Security: Support for standard PDF encryption (RC4, AES-128, AES-256).

Installation

pip install oxpdf

Or build from source using maturin:

cd oxpdf-python
maturin develop --release

Quickstart

1. Document Loading & Inspection

import oxpdf

# Load from file
doc = oxpdf.Document.from_file("annual_report.pdf")

# Or load from bytes
with open("annual_report.pdf", "rb") as f:
    doc = oxpdf.Document.from_bytes(f.read())

print(f"Total pages: {doc.page_count()}")
print(f"Total objects: {doc.object_count()}")
print(f"Page IDs: {doc.get_page_ids()}")

2. Layout-Aware Markdown Extraction

Convert complex documents into structured GitHub-Flavored Markdown with preserved headers and reconstructed tables:

import oxpdf

doc = oxpdf.Document.from_file("financial_statement.pdf")

# Extract entire document as Markdown
markdown = doc.to_markdown_all()
print(markdown)

# Or convert a specific page by ID
page_ids = doc.get_page_ids()
first_page_md = doc.to_markdown(page_ids[0])
print(first_page_md)

3. Extracting Plaintext

import oxpdf

doc = oxpdf.Document.from_file("document.pdf")

# Extract all pages
pages = doc.extract_text_all()
for idx, page_text in enumerate(pages, 1):
    print(f"--- Page {idx} ---")
    print(page_text)

# Or extract a specific page
page_ids = doc.get_page_ids()
text = doc.extract_text(page_ids[0])

4. Zero-Copy Image Extraction

Extract embedded images directly as JPEG or PNG without transcoding:

import oxpdf

doc = oxpdf.Document.from_file("presentation.pdf")

# Extract all images from the document
images = doc.extract_images_all()
print(f"Found {len(images)} images")

for img in images:
    print(f"Name: {img.name}, Format: {img.format}, Size: {img.width}x{img.height}")
    # Write image bytes directly to disk
    with open(f"{img.name}.{img.format}", "wb") as f:
        f.write(bytes(img.data))

API Reference

oxpdf.Document

• Document(data: bytes): Constructor from byte buffer.
• Document.from_bytes(data: bytes) -> Document: Load from bytes.
• Document.from_file(path: str) -> Document: Load from a file path.
• page_count() -> int: Returns the total number of pages.
• get_page_ids() -> list[int]: Returns indirect object IDs of all pages.
• extract_text(page_id: int) -> str: Extracts plaintext from a page.
• extract_text_all() -> list[str]: Extracts plaintext from all pages.
• to_markdown(page_id: int) -> str: Converts a page to layout-aware Markdown.
• to_markdown_all() -> str: Converts all pages to unified Markdown.
• extract_images(page_id: int) -> list[PyExtractedImage]: Extracts images from a page.
• extract_images_all() -> list[PyExtractedImage]: Extracts all images.
• object_count() -> int: Returns the total object count in the xref table.

oxpdf.PyExtractedImage

• name: str: Image resource identifier (e.g. /Im1).
• format: str: Image format (jpeg, png, rgb, gray).
• width: int: Image pixel width.
• height: int: Image pixel height.
• data: list[int]: Raw byte data.
• to_bytes() -> bytes: Direct Python bytes representation.

License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)