distillPDF

Turn any PDF into clean, LLM-ready HTML or Markdown — structure-aware, pure-Rust, MIT-licensed.

distillpdf does structure-aware PDF extraction: it reconstructs a document's structure — reading order, headings, paragraphs, lists, tables, and figures — then emits compact, semantic HTML or Markdown (or plain text) ready to feed to an LLM or a RAG pipeline. No styling noise, no layout junk. It's pure Rust on lopdf, shipped to Python via PyO3 + maturin as a small, self-contained wheel — a lightweight, permissively licensed alternative to AGPL/heavyweight extractors (PyMuPDF, pdfminer, Unstructured), with no system dependencies and no Python runtime deps.

OCR for scanned PDFs: detect image-only pages and turn them into clean HTML or a compact searchable PDF, with a bundled offline engine or an optional accurate VLM — OCR guide » · example notebook »

Install

pip install distillpdf

Prebuilt wheels — no compiler or system libraries required. Installing also puts a distillpdf command on your PATH.

Quickstart

import distillpdf

doc = distillpdf.open("paper.pdf")        # or distillpdf.from_bytes(data)

doc.to_html()                             # writes paper.html (one self-contained file)
doc.to_markdown()                         # writes paper.md + an img/ folder of figures

html     = doc.to_html(return_string=True)   # ...or get the rendered string back instead
text     = doc.extract_text()                # plain text, in reading order
abstract = doc.section("abstract")           # one section's HTML (or None if no match)

By default these methods write a file and return 1; pass return_string=True for the string. PDF to HTML/Markdown — full guide »

distillpdf paper.pdf                  # HTML to stdout
distillpdf paper.pdf -o paper.html    # ...or to a file (.md infers Markdown)
distillpdf paper.pdf --markdown       # Markdown to stdout
distillpdf *.pdf -o out/              # batch: out/<name>.html per input
distillpdf scan.pdf --ocr             # OCR a scan → scan.searchable.pdf (bundled, no extra)

Command-line guide »

What's in the box

• Rendering modes & image handling — section-first or page-first HTML/Markdown, an optional table of contents, and embed / external (an img/ folder) / drop image modes. Rendering »
• Raw extraction — extract_tables(), rich analyze_tables(), extract_images(), extract_links(), extract_fonts() give you the structured pieces, not rendered output. Extraction »
• The .dpdf document model — distill() once to a durable file, then re-render and query it forever with no source PDF and no re-analysis. .dpdf »
• Honest search — coverage-reporting lexical find() (never a silent miss) and opt-in semantic search() over BAAI/bge-m3 vectors stored inside the .dpdf. Search »
• OCR, two tiers — a bundled fast Tesseract engine (~0.8 s/page, offline, no download) and an optional accurate granite-docling VLM (structure + tables), folded into the same HTML / Markdown / searchable-PDF outputs. OCR » · setup »
• An agent shell over .dpdf — any shell with distillpdf installed can drive info / toc / read / find / search against a distilled model, no SDK or server. CLI »

Lazy engine (experimental)

Opt in with engine="lazy" to read the PDF container through an on-demand index instead of parsing it whole, keeping peak memory far below the file size on large documents:

doc = distillpdf.open("10000-pages.pdf", engine="lazy")
doc.engine          # "lazy"

The output is identical to the default engine="eager" — it is a memory strategy, not a fidelity choice, and it is regression-tested against the eager route as the oracle. Damaged cross-reference data is rebuilt in place by a bounded forward scan, so a broken file stays lazy; only the rare shapes the index refuses — an oversized object, an unusually deep page tree, an unusual encryption — fall back to the eager engine, so engine="lazy" never turns a readable PDF into an error. The fallback is never silent: doc.engine then reports "lazy (eager fallback)". Experimental in that the default engine may change in a future release — the keyword and its two values are stable. Lazy engine »

Comparison

Documentation

Full documentation — guides, the Python API reference, and the .dpdf format spec — lives at distillpdf.readthedocs.io. New here? Start with Getting started, then the Python API reference and the .dpdf format reference.

Early release — testers wanted

This is a young project and the API is small and may still change. If you have PDFs that come out wrong, please open an issue with the file (or a description) — real-world documents are exactly what this needs to get better. The .dpdf document model is also experimental (schema_version 0) and not yet a stable contract.

Contributing

Feedback is the fastest way to improve this. Try it on your PDFs and tell me where the output is wrong, star the repo if it's useful, and PRs are welcome. See Contributing and development to build from source or run the tests.

License

MIT — see LICENSE. Use it anywhere, including commercial and closed-source projects.