superPDF AI for Python

superPDF AI for Python: PDF to Markdown, Word and Excel, forms, merge and compare, on your computer. pip install superpdf; Node.js included.

superpdf is superPDF AI’s Python package: read PDFs into Markdown, HTML or JSON, convert them to Word, PowerPoint, Excel and EPUB, fill forms, compare versions, and merge, split, rotate, number and protect them. Everything runs on your computer; nothing is uploaded. It is on PyPI, with typed functions, and it includes a LangChain loader and a LlamaIndex reader.

Install

pip install superpdf

Or with uv, or as a command without installing anything:

uv add superpdf                 # in a uv project
uvx superpdf export report.pdf --output report.md
pipx run superpdf export report.pdf --output report.md

With the LangChain loader or the LlamaIndex reader:

pip install "superpdf[langchain]"
pip install "superpdf[llama-index]"

Versions and requirements

Check what you have with python --version, python -m pip --version and, after installing, python -c "import superpdf; print(superpdf.__version__)".

Read a PDF

import superpdf

# Headings, tables, charts as data, and OCR for scanned pages
markdown = superpdf.export("report.pdf")
html = superpdf.export("report.pdf", "html", pages="1-3")
structure = superpdf.export_json("report.pdf")  # title, pages, sections
for page in superpdf.export_pages("report.pdf"):  # Markdown per page
    print(page["page"], page["markdown"][:80])

export takes pages (such as "1,3-5"), tables="html" (Markdown with tables written as HTML, keeping merged header cells), ocr=False to skip OCR on scanned pages, and timeout in seconds (default 600).

Convert, edit and compare

Every superPDF tool is a typed function, the same tools as the MCP server and the local API, with the same checks and results:

superpdf.to_docx("report.pdf", "report.docx")  # editable Word
superpdf.extract_tables("report.pdf", "tables.xlsx")  # or .csv with format="csv"
superpdf.merge(["a.pdf", "b.pdf"], "combined.pdf")  # {"output", "pages", "bytes"}
superpdf.fill_form("form.pdf", {"Name": "Ada Lovelace", "Agree": True}, "filled.pdf")
superpdf.add_text("contract.pdf", "Signed: Ada Lovelace", "signed.pdf", x=72, y=96)
superpdf.protect("payslip.pdf", "a long password", "locked.pdf")  # AES-256

# Per page: same, changed, added or removed
changes = superpdf.compare("v1.pdf", "v2.pdf")

Outputs are always new files: a function never overwrites an existing one. Each call only uses the folders of the files you pass it. All functions lists every function, its options and what it returns.

Errors

Every failure raises superpdf.SuperPDFError with superPDF's own message, such as No file at report.pdf. or Invalid input. angle: use 90, 180 or 270.

try:
    superpdf.merge(["a.pdf", "b.pdf"], "combined.pdf")
except superpdf.SuperPDFError as error:
    # Invalid input. output: combined.pdf already exists.
    # superPDF never overwrites files; choose a new name.
    print(error)

The superpdf command

The package also installs the superpdf command (the same as python -m superpdf), which runs the full PDF CLI. superpdf help lists its commands.

superpdf export report.pdf --output report.md
superpdf tool pdf_to_docx --input '{"input":"report.pdf","output":"report.docx"}'
superpdf mcp --allow-dir ~/Documents/superPDF

Install ahead of time

To install the reader before the first call, for example in a Docker image or before going offline:

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

Source and releases

superPDF AI’s command-line tool, MCP server, local API and Python package are open source (Apache-2.0).

• Source code: github.com/arjunprabhulal/superpdf
• npm: @superpdf/cli
• PyPI: superpdf
• Changelog: CLI and Python
• Report a problem: GitHub issues