superpdf (Python)

Read PDFs into Markdown, HTML or JSON on your computer: headings, tables, charts as data and OCR for scanned pages. 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 (merge, split, extract, rotate, page numbers, watermark, protect, unlock, repair, 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 185 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 18 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

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.