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

> Discover olmOCR example usage with our quick-start guide. Explore CLI and Python API examples for local GPU, remote inference, Docker, and async PDF processing.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: getting-started
- Published: 2026-07-08

---

**You can find olmOCR example usage in the repository README, the [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) source, and the [`tests/test_pipeline.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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:

```bash

# 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](https://github.com/allenai/olmocr/blob/main/README.md#usage-examples)

### Batch Processing with Wildcards

Process an entire directory of PDFs at once:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py).

### Async Page Processing

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

```python
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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py)): Defines `LocalBackend`, `S3Backend`, and `WorkQueue` for distributing PDFs across workers.
- **PDF processing pipeline** ([`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/prompts.py) and [`olmocr/prompts/anchor.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) for async programmatic access.
- **Scalability**: The `WorkQueue` abstraction in [`olmocr/work_queue.py`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py) enables multi-node processing via S3.
- **Rendering**: PDF-to-PNG conversion happens in [`olmocr/data/renderpdf.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/prompts.py) (specifically the `build_no_anchoring_v4_yaml_prompt` function), with anchor text logic in [`olmocr/prompts/anchor.py`](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/anchor.py). These files define how the model structures its Markdown response and extracts metadata like language and rotation.