Example Usage of olmOCR: CLI and Python API Quick‑Start Guide

You can find olmOCR example usage in the repository README, the olmocr/pipeline.py source, and the tests/test_pipeline.py unit tests, covering CLI commands for local GPU, remote inference, Docker, and S3 clusters, plus async Python APIs for programmatic PDF processing.

The allenai/olmocr toolkit converts PDF documents into clean Markdown text using vision-language models. To help you get started, the maintainers provide extensive example usage patterns that demonstrate how to run the pipeline from the command line, call it programmatically from Python, and deploy it across distributed infrastructure. The following sections extract the canonical invocation patterns directly from the source code.

Command‑Line Interface Examples

The fastest way to explore olmOCR is through the CLI entry point defined in olmocr/pipeline.py. These examples assume you have installed the package via pip install olmocr or are running inside the official Docker container.

Single PDF Conversion (Local GPU)

Download a sample PDF and convert it to Markdown with a single command:

# Fetch a demo PDF from the project hosts

curl -o olmocr-sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf

# Process the PDF (outputs appear in ./localworkspace/markdown/)

olmocr ./localworkspace --markdown --pdfs olmocr-sample.pdf

Source: README – Usage Examples

Batch Processing with Wildcards

Process an entire directory of PDFs at once:

olmocr ./localworkspace --markdown --pdfs tests/gnarly_pdfs/*.pdf

This command writes Dolma JSONL files to ./localworkspace/results/ and Markdown files to ./localworkspace/markdown/. The glob pattern is expanded by your shell before the CLI receives the paths.

Remote Inference Server

If you lack local GPU resources, install the lightweight package and point to a remote vLLM or OpenAI‑compatible endpoint:

pip install olmocr

olmocr ./localworkspace \
  --server http://remote-server:8000/v1 \
  --model allenai/olmOCR-2-7B-1025-FP8 \
  --markdown \
  --pdfs *.pdf

The --server flag instructs the client to POST rendered pages to the supplied URL, while --model specifies the model name registered on that endpoint.

Docker Deployment

For a fully contained environment including the 30 GB model weights, use the official image:

docker pull alleninstituteforai/olmocr:latest-with-model

docker run --gpus all \
  -v $(pwd):/workspace \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /workspace/output --markdown --pdfs /workspace/sample.pdf"

This eliminates the need to install CUDA dependencies or download weights manually.

Multi‑Node S3 Work‑Queue

To scale across many workers, initialize a shared queue on S3:

# Worker 1: creates the queue and starts processing

olmocr s3://my_bucket/pdfworkspaces/exampleworkspace \
  --pdfs s3://my_bucket/jakep/gnarly_pdfs/*.pdf

# Worker N: joins existing queue and picks up remaining items

olmocr s3://my_bucket/pdfworkspaces/exampleworkspace

The WorkQueue implementation in olmocr/work_queue.py automatically balances load across all participants using S3Backend or LocalBackend abstractions.

Programmatic Python API

For integration into larger applications, import the async functions from olmocr/pipeline.py.

Async Page Processing

Build a query for a specific page and send it to the inference server:

from olmocr.pipeline import build_page_query, try_single_page

# Construct the query for page 1 (requires a running vLLM server)

query = await build_page_query(
    local_pdf_path="mydoc.pdf",
    page=1,
    target_longest_image_dim=1024,
    model_name="allenai/olmOCR-2-7B-1025-FP8",
)

# Execute the query (args namespace mimics CLI options)

result = await try_single_page(
    args=args,               # populated via argparse in pipeline.main()

    pdf_orig_path="mydoc.pdf",
    pdf_local_path="mydoc.pdf",
    page_num=1,
    attempt=0,
    rotation=0,
)
print(result.response.natural_text)

These helpers are exercised in tests/test_pipeline.py, which demonstrates how to mock HTTP calls for unit testing.

Core Architecture and Source Files

Understanding the three-layer architecture helps you locate specific example usage patterns:

• Work‑queue manager (olmocr/work_queue.py): Defines LocalBackend, S3Backend, and WorkQueue for distributing PDFs across workers.
• PDF processing pipeline (olmocr/pipeline.py): Contains the main entry point and async functions process_page, process_single_pdf, and build_dolma_document that handle rendering, inference, and output formatting.
• Prompt generation (olmocr/prompts/prompts.py and olmocr/prompts/anchor.py): Generates system prompts via build_no_anchoring_v4_yaml_prompt and computes anchor text for fallback scenarios.
• PDF rendering (olmocr/data/renderpdf.py): Converts PDF pages to base‑64 PNG images for model consumption.

Summary

• CLI entry: The olmocr command in olmocr/pipeline.py supports local GPU, remote servers, Docker, and S3 clusters.
• Python API: Use build_page_query and try_single_page from olmocr/pipeline.py for async programmatic access.
• Scalability: The WorkQueue abstraction in olmocr/work_queue.py enables multi-node processing via S3.
• Rendering: PDF-to-PNG conversion happens in olmocr/data/renderpdf.py before being sent to the vision model.

Frequently Asked Questions

Where is the main entry point for olmOCR processing?

The main function in olmocr/pipeline.py serves as the primary entry point for both CLI and programmatic execution. It coordinates PDF rendering, model inference, and output serialization.

How do I run olmOCR without a local GPU?

Install the lightweight package with pip install olmocr and specify a remote endpoint using the --server flag. This delegates inference to a vLLM or OpenAI‑compatible server while your local machine handles pre‑processing and post‑processing.

Can I process PDFs stored in S3 using olmOCR?

Yes. Pass an S3 URI as the workspace path (e.g., s3://bucket/workspace) and include S3 paths in the --pdfs argument. The S3Backend in olmocr/work_queue.py manages file synchronization and distributed locking across workers.

What file contains the prompt templates used by olmOCR?

The system prompts are generated in olmocr/prompts/prompts.py (specifically the build_no_anchoring_v4_yaml_prompt function), with anchor text logic in olmocr/prompts/anchor.py. These files define how the model structures its Markdown response and extracts metadata like language and rotation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}