Backends
document2md converts through one of two backends: mineru (OCR and layout analysis) or pymupdf (reading a PDF’s own embedded text layer, no OCR). --backend/BatchConverter(backend=...) picks between them, defaulting to "auto".
The auto rule
auto resolves to mineru when the mineru CLI is on PATH, otherwise to pymupdf. mineru has given the best results and remains the reference backend wherever it’s installed — auto never prefers the lighter backend over an installed mineru. The light backend exists to make installing mineru optional, not to replace it where it’s present.
mineru |
pymupdf |
|
|---|---|---|
| Quality | Reference: the best structure document2md produces | Slightly worse structure |
| Speed | Slow: runs real layout/OCR models | Orders of magnitude faster |
| Install size | Heavy (mineru[pipeline], an optional extra, plus system OpenCV packages) |
Small, core dependency |
| What it can read | PDFs and scanned page images, digital or scanned alike | Only a PDF with enough of an embedded text layer |
| Figures | Extracted, alongside the Markdown | Not extracted |
What counts as “enough” of a text layer
The pymupdf backend can’t tell the difference between a scanned PDF and one it simply doesn’t understand, so it decides up front, page by page: a page counts as text-bearing when its extracted text has at least 50 non-whitespace characters, and the PDF as a whole qualifies when at least 80% of its pages are text-bearing — a whole-document decision, tolerating a handful of scanned inserts in an otherwise born-digital document. A fully scanned PDF always fails this check.
A list of scanned page images always needs OCR — under pymupdf it’s rejected outright, the same as a PDF that fails the text-layer check. Neither case falls back silently to mineru: document2md raises an error naming pip install "document2md[mineru]" instead, so the choice stays visible rather than hidden behind a slow, surprising OCR pass. See Command line for the exact wording.
Forcing a backend
- Force
mineru(--backend mineru) when you want the best structure, or a scanned document, and don’t mind the wait or the install size. - Force
pymupdf(--backend pymupdf) when you know every document in a batch is born-digital and want to fail fast (RuntimeError, not a long OCR pass) on the rare one that turns out not to be. - Leave it at
auto(the default) otherwise: it picks the best backend actually available, without forcing an install either way.
How the output differs
Both backends produce Markdown; the two differ in what they can capture from the source PDF:
- Headings.
mineruinfers structure from its layout model;pymupdfinfers headings from font sizes. - Tables.
mineru‘s complex tables (rowspan/colspan) arrive as raw HTML and are rewritten into Markdown tables by document2md itself (see the developer docs’ architecture page);pymupdf4llmemits Markdown tables directly via PyMuPDF’s own table finder. - Figures.
mineruextracts figures alongside the Markdown, into<md stem>_images/;pymupdfextracts none.