Documents in, structure out.

Four stages, every page

1. Read the text layerpdfium gives every character with its box, font size and weight. Exact, and about 10 ms per page.
2. OCR only where neededPages with no text layer or a broken font encoding are straightened and sent to OCR. Lines the engine skipped are re-read from tight crops.
3. Rebuild the layoutReading order by XY-cut, tables from ruling lines or aligned columns, headings from size, weight and numbering, lists, hyphenation.
4. ExportMarkdown, plain text, JSON, or the Python objects directly, with page numbers and bounding boxes.

One package, an OCR engine per platform

Digital PDFs and Word files need nothing beyond the base install. Scans and images need an OCR engine: foliodoc[ocr] installs the right ones for your platform, and ocr="auto" uses the first one available, in the order below. The source is on GitHub.

pip install foliodoc              # digital PDFs and Word files only
pip install "foliodoc[ocr]"       # + OCR: Apple Vision on macOS, RapidOCR everywhere

Convert a file in three lines

from foliodoc import convert

doc = convert("report.pdf")      # or scan.png, photo.jpg, fax.tiff, contract.docx
print(doc.to_markdown())

A Document is plain Python objects, so you can also walk it directly:

for block in doc.blocks:
    if block.type == "heading":
        print("  " * (block.level - 1) + block.text)

for table in doc.tables:           # each table is a list of rows of cell strings
    header, *rows = table
    print(header, len(rows), "rows")

print(doc.timings)                 # {'total_s': 0.04, 'per_page_s': 0.02, ...}

Everything you import

convert(source, **options) → Document

Converts one file. source is a path or raw bytes (PDF, PNG, JPEG, TIFF including multi-page, BMP, GIF, WebP, DOCX). Options are the same as Converter's.

Converter(**options)

Reuse one converter for many files: the OCR engine loads once. Call .convert(source) on it.

Document

Block

Batch conversion from a shell

foliodoc report.pdf                                 # Markdown to stdout
foliodoc *.pdf scans/*.png -o out/ --to md          # one out/<name>.md per file
foliodoc invoice.pdf --to json --timings            # JSON, and timings on stderr
foliodoc fax.tiff --ocr rapidocr --dpi 300
foliodoc old_scan.pdf --force-ocr                   # ignore a bad embedded text layer

Common tasks

Tables to pandas

import pandas as pd
from foliodoc import convert

doc = convert("annual_report.pdf")
frames = [pd.DataFrame(rows, columns=header) for header, *rows in doc.tables]

A folder of mixed files, one converter

from pathlib import Path
from foliodoc import Converter

conv = Converter(ocr="rapidocr")          # models load once
for path in Path("inbox").iterdir():
    doc = conv.convert(path)
    Path("out", path.stem + ".md").write_text(doc.to_markdown())

Chunks for search or RAG, with page citations

chunks, section = [], ""
for b in convert("handbook.pdf").blocks:
    if b.type in ("title", "heading"):
        section = b.text
    elif b.type in ("paragraph", "list_item"):
        chunks.append({"section": section, "page": b.page, "text": b.text})

Scans in other languages

doc = convert("brochure_zh.png", ocr="apple", languages=["zh-Hans", "en-US"])

Text only, never OCR

doc = convert("contract.pdf", ocr="none")   # fastest; scanned pages come back empty
if any(p.ocr for p in doc.pages): ...           # with OCR on, see which pages needed it

Plug in your own OCR engine

An engine is a function from a PIL image to text lines with pixel boxes. Register it once and select it by name.

from foliodoc import Segment, convert, register_ocr_engine

@register_ocr_engine("my-ocr")
def make_engine():
    client = MyOcrClient()                       # load models once
    def run(image):
        return [Segment(line.text, *line.box, size=line.height * 0.78, conf=line.score)
                for line in client.read(image)]
    return run

doc = convert("scan.png", ocr="my-ocr")

7,822 public documents against docling

Four public datasets with ground truth: 4,999 DocLayNet digital PDF pages, 1,651 OmniDocBench page images, 973 SROIE receipts and 199 FUNSD forms. Both tools ran one after the other on an Apple M2 with default settings, which on macOS means Apple Vision OCR for both. Docling version 2.63.

Windows and Linux configuration

Both tools with RapidOCR, the OCR they use off macOS. This ran on a subset (all FUNSD forms, the SROIE test split, 493 English and mixed-language OmniDocBench pages). DocLayNet needs no OCR, so its numbers above hold on every OS.

• Every system is scored on exactly the same documents. A document a tool failed on counts as empty output, except in rows marked "both read".
• Docling's layout model was trained on DocLayNet. 102 DocLayNet pages whose own ground-truth text is garbled are excluded for both tools.
• Docling's 214 failures are large images it rejects after internal upscaling (Pillow's 179-megapixel safety limit).
• Text edit distance is normalized Levenshtein distance of the page text in reading order (0 is perfect). TEDS is the standard tree-edit similarity for tables (1 is perfect).
• Reproduce with the scripts in bench/: real_prep.py, real_run.py, real_score.py.

Know before you rely on it

• Layout on complex real documents is foliodoc's weak point. If you need precise table structure or section labels from reports and papers, docling's trained models do better today.
• OCR quality depends on the engine: best with Apple Vision on macOS; RapidOCR on Windows and Linux runs at roughly 3–8 s per scanned page on a laptop CPU.
• Formulas are returned as plain text, not LaTeX. Figures are marked but not described. Handwriting is only as good as the OCR engine.
• Non-Latin scripts need the OCR language set explicitly (languages=[...] with Apple Vision).