How to Run olmOCR from the Command Line: A Complete Guide to the allenai/olmocr CLI

You can run olmOCR from the command line by installing the olmocr package via pip and invoking olmocr <workspace> --pdfs <paths> to process PDFs locally, remotely, or across distributed S3 infrastructure.

The allenai/olmocr repository provides a production-ready command-line interface for converting PDF documents into structured text. The olmocr CLI serves as a thin wrapper around the core processing pipeline defined in olmocr/pipeline.py, coordinating PDF rendering, vision-language model inference, and Dolma-compatible output generation. Whether processing a single research paper or millions of documents stored in cloud storage, the command line tool offers flexible execution modes to match your infrastructure.

Installation and Prerequisites

Before you can run olmocr from the command line, install the package using pip. The installation varies depending on whether you intend to use local GPU inference or connect to a remote server.

For local GPU inference (includes vLLM dependencies):

pip install olmocr[gpu]

For lightweight installation (remote inference only):

pip install olmocr

Basic Command Structure

Every olmOCR command requires a workspace directory as the first positional argument. This workspace stores configuration, downloaded models, and output results.

The basic syntax follows this pattern:

olmocr <workspace> [options] --pdfs <pdf_paths>

Key arguments include:

• --markdown: Generates Markdown output alongside JSONL results
• --workers N: Configures parallelism (default: 20)
• --server URL: Routes inference to a remote OpenAI-compatible endpoint

Execution Modes

The CLI supports three primary execution modes controlled by specific flags.

Local GPU Inference

By default, olmOCR starts an embedded VLLM server on your local GPU. This mode requires the [gpu] extras and sufficient VRAM to load the model.

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

Remote Inference

To use an external VLLM server or API endpoint, specify the --server and --model flags:

olmocr ./my_workspace \
    --server http://my-vllm-instance:8000/v1 \
    --model allenai/olmOCR-2-7B-1025-FP8 \
    --markdown \
    --pdfs *.pdf

Distributed S3 Work Queue

For large-scale processing, olmOCR supports S3-backed work queues that enable multiple workers to coordinate via the S3Backend class in olmocr/work_queue.py:

olmocr s3://my-bucket/olmocr-workspace \
    --pdfs s3://my-bucket/pdfs/*.pdf \
    --workers 40 \
    --markdown

How the Pipeline Works

Understanding the internal architecture helps optimize command-line usage. When you invoke olmocr, the main() function in olmocr/pipeline.py orchestrates the following workflow:

1. Argument Parsing: argparse builds a configuration object (see line 1199 in pipeline.py)
2. Model Loading: The download_model() function fetches weights from Hugging Face, local directories, or S3
3. Work Queue Initialization: The system creates work items using LocalBackend or S3Backend implementations from olmocr/work_queue.py
4. Worker Processing: Each worker (default 20) executes the pipeline:
   • Downloads PDFs via utilities in olmocr/s3_utils.py
   • Optionally filters documents using olmocr/filter/filter.py
   • Renders pages to base-64 PNGs via olmocr/data/renderpdf.py
   • Sends inference requests using the lightweight HTTP client
   • Handles rotation errors and pdftotext fallback
5. Result Aggregation: The build_dolma_document() function aggregates pages into Dolma-compatible JSONL, while get_markdown_path() handles Markdown output

Practical Examples

Processing a Single PDF

Download a sample and convert it to Markdown:

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

Results appear in ./my_workspace/results/ as JSONL, with Markdown files in ./my_workspace/markdown/.

Docker Execution

Run olmOCR in a GPU-enabled container without local installation:

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

Advanced Configuration

Language and Spam Filtering

Enable content filtering before OCR processing by utilizing the filter implementation in olmocr/filter/filter.py. This subsystem checks documents against language and spam criteria during the worker loop.

Custom Worker Counts

Adjust parallelism based on your infrastructure. The default of 20 workers suits most local setups, but S3-backed distributed runs often benefit from 40+ workers:

olmocr s3://bucket/workspace --workers 40 --pdfs s3://bucket/pdfs/*.pdf

Summary

• Install olmOCR via pip install olmocr[gpu] for local inference or pip install olmocr for remote usage
• Execute using olmocr <workspace> --pdfs <paths> with optional --markdown flag
• Choose between three modes: local GPU (default), remote server (--server), or distributed S3 (s3:// workspace)
• Understand that olmocr/pipeline.py handles orchestration via main(), download_model(), and build_dolma_document()
• Scale processing by adjusting --workers and using S3-backed queues for massive parallelism

Frequently Asked Questions

How do I process PDFs stored in Amazon S3?

Specify an S3 path as your workspace and use S3 glob patterns for the PDFs argument. The CLI automatically uses the S3Backend class from olmocr/work_queue.py to coordinate distributed processing across multiple workers, writing results back to s3://bucket/workspace/results/.

Can I run olmOCR without a local GPU?

Yes. Use the --server flag to point to any OpenAI-compatible inference endpoint. Install the lightweight package with pip install olmocr (without [gpu]), and specify the model ID and server URL. The pipeline will send base-64 encoded page images to the remote endpoint instead of running vLLM locally.

Where are the OCR results saved?

By default, JSONL documents are written to <workspace>/results/ using the build_dolma_document() function in olmocr/pipeline.py. If you include the --markdown flag, plain-text versions are also saved to <workspace>/markdown/ via the get_markdown_path() function.

What happens if a PDF fails to process?

The pipeline includes robust error handling in olmocr/pipeline.py. Workers attempt rotation retries for misaligned pages and automatically fall back to pdftotext when the vision model fails. Failed documents are logged, and the queue continues processing remaining items without stopping the entire job.

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