Skip to content
pdf-textlayer
Esc
↑↓navigate↵open⌘Jpreview
On this page

Python

The pdf_textlayer Python API — make_searchable_pdf, write_textlayer, add_textlayer, load_pages, and the TextBox, ParsedPage, Options, and Stats types.

pip install pdf-textlayer
uv add pdf-textlayer

Python 3.11 or newer. One wheel per platform (abi3) with no runtime dependencies. The package is fully typed (py.typed). Every function runs in Rust with the GIL released, so threads that call it run in parallel.

from pdf_textlayer import Options, make_searchable_pdf

stats = make_searchable_pdf(
    "input.pdf",
    "parsed.json",
    "output.pdf",
    options=Options(min_confidence=0.5),
)

Functions

make_searchable_pdf

def make_searchable_pdf(
    input_pdf: str | os.PathLike[str],
    source: str | os.PathLike[str] | Mapping[str, Any] | Iterable[ParsedPage],
    output_pdf: str | os.PathLike[str],
    *,
    adapter: str = "liteparse",
    options: Options | None = None,
) -> Stats

Reads OCR JSON with an adapter and writes the searchable PDF. source is a path to a JSON file or the already-loaded document (a dict). It may also be an iterable of ParsedPage, in which case adapter is ignored.

write_textlayer

def write_textlayer(
    input_pdf: str | os.PathLike[str],
    pages: Iterable[ParsedPage],
    output_pdf: str | os.PathLike[str],
    *,
    options: Options | None = None,
) -> Stats

Writes the PDF from boxes you already have. Pages not listed in pages, or left with no drawable boxes, are copied unchanged. Order does not matter.

add_textlayer

def add_textlayer(
    pdf: bytes,
    pages: Iterable[ParsedPage],
    *,
    options: Options | None = None,
) -> tuple[bytes, Stats]

Same as write_textlayer for a PDF held in memory. Returns the new PDF and its stats.

load_pages

def load_pages(
    source: str | os.PathLike[str] | Mapping[str, Any],
    *,
    adapter: str = "liteparse",
) -> list[ParsedPage]

Returns the pages an adapter reads from OCR JSON, so you can inspect, filter, or fix boxes before writing them. Pages without OCR boxes are omitted, and malformed pages and items are skipped.

from pdf_textlayer import load_pages, write_textlayer

pages = load_pages("parsed.json")
pages = [page for page in pages if page.page_number != 3]  # leave page 3 alone
write_textlayer("input.pdf", pages, "output.pdf")

main

def main(argv: list[str] | None = None) -> int

Runs the CLI with argv (default sys.argv[1:]) and returns its exit code. The pdf-textlayer command calls it.

Types

TextBox

@dataclass(frozen=True)
class TextBox:
    text: str
    x: float
    y: float
    width: float
    height: float
    confidence: float = 1.0
    rotation: float = 0.0

One piece of OCR text, in PDF points, with (x, y) the top-left corner of the box on the displayed page. rotation is degrees counter-clockwise. See Coordinates.

ParsedPage

@dataclass(frozen=True)
class ParsedPage:
    page_number: int  # 1-indexed page of the input PDF
    boxes: list[TextBox] = field(default_factory=list)

Options

@dataclass(frozen=True)
class Options:
    min_confidence: float = 0.0
    font: str = "helv"
    sanitize_unsupported: bool = True
Field Description
min_confidence Drop boxes whose confidence is below this (0–1). 0.0 keeps everything, including a confidence of exactly 0.
font Whose character widths size each run: helv, tiro, or cour. Changes spacing, not appearance. See Fonts.
sanitize_unsupported Replace characters that cannot be drawn with ?. When False, boxes containing one are dropped.

Stats

class Stats(TypedDict):
    pages: int            # pages in the document
    ocr_pages: list[int]  # 1-indexed pages that received a text layer
    items_drawn: int      # boxes drawn across all pages

Errors

Exception Raised when
FileNotFoundError The input PDF or the JSON file does not exist.
OSError Another file error, such as an unwritable output path.
pdf_textlayer.PdfError The input is not a readable PDF, or it is encrypted. Subclass of RuntimeError.
ValueError An unknown adapter or font, or JSON that does not parse.

Nothing is written when an error is raised.

Was this page helpful?