LLM OCR

Turn PDFs and images into clean Markdown with vision LLMs:
Gemini, OpenAI, Claude, or a local model through Ollama.

pip install ocr-llm
export GEMINI_API_KEY="..."   # or OPENAI_API_KEY / ANTHROPIC_API_KEY
ocr-llm document.pdf -o document.md

Or from Python:

from llm_ocr import LLMOCR, Gemini

markdown = LLMOCR(Gemini()).convert_sync("document.pdf")

It handles multi-page PDFs concurrently, keeps pages in order, retries failed requests, and works with any OpenAI-compatible server.

Installation

pip install ocr-llm

Gemini and OpenAI work out of the box. Claude needs an extra:

pip install "ocr-llm[anthropic]"

PDF input needs poppler: brew install poppler on macOS, sudo apt-get install poppler-utils on Debian/Ubuntu. Images work without it.

Providers

Keys are read from the environment, or passed as api_key=. Choose a model with model=: either a constant such as Gemini.PRO_2_5 or any model name as a string, so new models work without a library update.

from llm_ocr import Anthropic, Gemini, OpenAI

Gemini(model=Gemini.PRO_2_5)
Anthropic(model="claude-haiku-5-5")

# Ollama, vLLM, LM Studio, OpenRouter: anything that speaks the OpenAI API
OpenAI(base_url="http://localhost:11434/v1", model="llava")

Local models with Ollama

Two Ollama server settings matter:

• Context length. At the default 200 DPI a page takes about 4,300 tokens with qwen2.5vl, more than the 4,096-token context Ollama picks on machines with little memory, so every page fails. Start the server with OLLAMA_CONTEXT_LENGTH=8192, or lower dpi.
• Parallel requests. Ollama works on OLLAMA_NUM_PARALLEL requests at a time (often 1) and queues the rest, so a max_concurrency above that does not make it faster. Set them to the same value. Servers built for batching, such as vLLM, do benefit from higher concurrency.

OLLAMA_CONTEXT_LENGTH=8192 ollama serve
ollama pull qwen2.5vl:3b
ocr-llm document.pdf --base-url http://localhost:11434/v1 --model qwen2.5vl:3b --concurrency 1

For a server on this machine (localhost), requests time out after 30 minutes instead of the OpenAI SDK's 10, so pages waiting in the queue are not cancelled and sent again. Pass timeout= (in seconds) to OpenAI(...) to change it.

Usage

convert_sync is the simplest entry point and also works in notebooks:

from llm_ocr import LLMOCR, OpenAI

ocr = LLMOCR(OpenAI())
markdown = ocr.convert_sync("document.pdf", output_path="document.md")

In async code, use convert and its siblings:

import asyncio

from llm_ocr import LLMOCR, Gemini


async def main():
    async with LLMOCR(Gemini()) as ocr:
        report = await ocr.convert("report.pdf")
        receipt = await ocr.convert("receipt.png")  # images work too

        # bytes from an upload or object store; PDF or image is detected
        with open("report.pdf", "rb") as f:
            from_bytes = await ocr.convert_bytes(f.read())


asyncio.run(main())

convert_image also accepts raw bytes or a PIL.Image.Image.

Command line

# Uses whichever of GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY is set
ocr-llm document.pdf -o document.md

ocr-llm scan.png --provider anthropic --instructions "Tables only"

ocr-llm document.pdf --base-url http://localhost:11434/v1 --model llava

Without -o, the Markdown goes to stdout. ocr-llm --help lists every option.

Configuration

from llm_ocr import LLMOCR, OCRConfig, OpenAI

config = OCRConfig(
    dpi=300,
    max_concurrency=8,
    additional_instructions="Write formulas in LaTeX.",
)
ocr = LLMOCR(OpenAI(), config=config)

Logging

Progress is reported through the standard logging module (it was print() before 1.1.0). To see it:

import logging

logging.basicConfig(level=logging.INFO)

Warnings, such as a page the model returned no text for, appear on stderr even without this. Such pages are left out of the output, so check for them.

Project

Changelog · Contributing · Roadmap · MIT License