superPDF AI for Python (superpdf)

superpdf.ai · Python docs · GitHub · Changelog

Read, convert, edit and compare PDFs on your computer: Markdown, HTML or JSON with headings, tables, charts as data and OCR for scanned pages; Word, PowerPoint, Excel and EPUB; forms, signatures, merging and splitting. Nothing is uploaded.

This package is a thin Python wrapper around the superPDF command-line tool (npm package @superpdf/cli), so you get exactly what superpdf export produces. Every superPDF tool is a typed Python function (Word, PowerPoint and EPUB export, tables to Excel or CSV, forms, merge, split, rotate, page numbers, watermark, protect, compare, Office to PDF, pipelines and batches), and it includes a LangChain document loader and a LlamaIndex reader.

Requirements

Python 3.10 or later on macOS, Linux or Windows. Nothing else: Node.js comes with the package through nodejs-wheel-binaries.

The first call installs the superPDF reader (@superpdf/cli, about 220 MB with its PDF engine and OCR language data) from npm into your cache folder, once. To do that ahead of time, for example in a Docker image or before going offline:

python -c "import superpdf; superpdf.install_cli()"

Install

pip install superpdf
pip install "superpdf[langchain]"      # with the LangChain loader
pip install "superpdf[llama-index]"    # with the LlamaIndex reader
uv add superpdf                        # in a uv project

Or run the command without installing anything:

uvx superpdf export report.pdf --output report.md
pipx run superpdf export report.pdf --output report.md

Use

import superpdf

markdown = superpdf.export("report.pdf")  # the whole document as Markdown
html = superpdf.export("report.pdf", "html")
structure = superpdf.export_json("report.pdf")  # pages, blocks with type and position, sections

for page in superpdf.export_pages("report.pdf"):  # Markdown per page
    print(page["page"], page["markdown"][:80])

superpdf.export("report.pdf", pages="1,3-5", tables="html", ocr=False)

Errors raise superpdf.SuperPDFError with superPDF's own message, for example No file at report.pdf.

Every PDF tool

Every superPDF tool is a Python function: the same 30 tools as the MCP server and the local API, with the same validation and results. Each returns a typed dict; outputs are always new files (an existing file is never overwritten), and a call only touches the folders of the files you give it.

import superpdf

superpdf.merge(["a.pdf", "b.pdf"], "combined.pdf")  # {"output": ..., "pages": 7, "bytes": ...}
superpdf.extract_pages("report.pdf", "1, 3-5", "selected.pdf")
superpdf.rotate_pages("scan.pdf", "upright.pdf", pages="2", angle=180)
superpdf.split("book.pdf", "chapters/", pages="1-10, 11-20")  # one PDF per range
superpdf.add_page_labels("report.pdf", "numbered.pdf", text="Page {page} of {total}")
superpdf.add_watermark("contract.pdf", "DRAFT", "draft.pdf")
superpdf.protect("payslip.pdf", "a long password", "locked.pdf")  # AES-256
superpdf.unlock("locked.pdf", "open.pdf", password="a long password")
superpdf.from_office("slides.pptx", "slides.pdf")  # needs LibreOffice

superpdf.to_docx("report.pdf", "report.docx")  # editable Word: headings, lists, tables
superpdf.extract_tables("report.pdf", "tables.xlsx")  # or tables.csv with format="csv"
superpdf.fill_form("form.pdf", {"Name": "Ada Lovelace", "Agree": True}, "filled.pdf")
superpdf.add_text("contract.pdf", "Signed: Ada Lovelace", "signed.pdf", pages="3", x=72, y=96)
changes = superpdf.compare("v1.pdf", "v2.pdf")  # per page: same, changed, added or removed

info = superpdf.info("report.pdf")  # pages, sizes, form fields, properties
text = superpdf.read_text("report.pdf", pages="1-2")  # the text layer, page by page

pages takes numbers and ranges such as "1, 3-5". Pipeline and batch steps are dicts such as {"action": "rotate", "options": {"pages": "1", "angle": 90}}; the actions are extract, remove, rotate, crop (margin), scale (factor), flatten, labels, watermark and metadata-clear.

superpdf.tools() lists every tool with its JSON input schema, and superpdf.run_tool(name, arguments, allow=[...]) runs any of them by name, for tools added to the CLI before this package catches up.

LangChain

from superpdf.langchain import SuperPDFLoader

docs = SuperPDFLoader("report.pdf").load()  # one Document per page
docs[0].metadata  # {"source": "report.pdf", "page": 1}

LlamaIndex

from superpdf.llama_index import SuperPDFReader

docs = SuperPDFReader(tables="html").load_data("report.pdf")  # one Document per page

Command line

The package installs a superpdf command that runs the full CLI (the same as python -m superpdf):

superpdf export report.pdf --output report.md
superpdf export report.pdf --tables html --output report.md
superpdf help

uvx superpdf … and pipx run superpdf … run it in a temporary environment, with nothing to install first.

How it works

Each call runs superpdf export in a subprocess (no shell) with the bundled Node.js and reads its output as UTF-8. The reader is @superpdf/cli at the version this package is tested with, installed once into your cache folder: ~/Library/Caches/superpdf on macOS, ~/.cache/superpdf on Linux and %LOCALAPPDATA%\superpdf\Cache on Windows (set SUPERPDF_CACHE_DIR to change it). To use your own build instead, set SUPERPDF_BIN to a superpdf command or superpdf.js. The reader, its tables, charts and OCR are described in the main README.

License

Apache-2.0.