How to Install olmOCR: Complete Setup Guide for Local and Remote Inference

Install olmOCR via pip install olmocr for lightweight remote inference, or pip install "olmocr[gpu]" for local GPU execution, ensuring you have Python 3.11 and Poppler system dependencies installed first.

The allenai/olmocr repository provides a Python-based OCR toolkit that converts PDFs and images into clean Markdown using vision-language models. Whether you need a lightweight client for remote inference or a full GPU-accelerated pipeline, understanding how to install olmocr correctly ensures optimal performance. This guide covers all installation flavors defined in pyproject.toml, from minimal setups to complete local deployments.

Prerequisites and System Dependencies

Before installing the Python package, you must install system-level dependencies for PDF processing. The olmocr/image_utils.py module relies on Poppler for rendering PDF pages to images, while the filtering components in olmocr/filter/filter.py expect specific font libraries for document analysis.

Install Poppler and Fonts (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install poppler-utils \
    ttf-mscorefonts-installer msttcorefonts \
    fonts-crosextra-caladea fonts-crosextra-carlito \
    gsfonts lcdf-typetools

Set Up Your Python Environment

Create an isolated Conda environment to avoid dependency conflicts, as the package pins specific versions of PyTorch and transformers.

conda create -n olmocr python=3.11
conda activate olmocr

Installation Methods

The pyproject.toml file defines four optional dependency groups in [project.optional-dependencies] tailored to different use cases. Choose the flavor that matches your hardware and workflow.

Remote Inference (Lightweight)

Install only the core library without PyTorch or CUDA dependencies. This connects to external vLLM servers via the --server flag implemented in olmocr/pipeline.py.

pip install olmocr

Local GPU Installation

Install the full stack including torch, transformers, and vllm for local inference. This requires an NVIDIA GPU with at least 12GB VRAM.

pip install "olmocr[gpu]" --extra-index-url https://download.pytorch.org/whl/cu128

Optionally add FlashInfer for faster CUDA inference:

pip install https://download.pytorch.org/whl/cu128/flashinfer/flashinfer_python-0.2.5%2Bcu128torch2.7-cp38-abi3-linux_x86_64.whl

Beaker Cluster Setup

For large-scale batch jobs on AI2 Beaker infrastructure, install the Beaker dependencies:

pip install "olmocr[beaker]"

This enables the CLI flags for submitting jobs to Beaker clusters, utilizing the distributed work queue implementation in olmocr/work_queue.py.

Benchmark Suite Installation

To run the comprehensive olmOCR-Bench validation suite (7k+ test cases), install the benchmark dependencies:

pip install "olmocr[bench]"

You can combine flavors. For example, to install both GPU and benchmark dependencies:

pip install "olmocr[gpu,bench]" --extra-index-url https://download.pytorch.org/whl/cu128

Verify the Installation

Confirm the CLI entry point is accessible. The olmocr command is defined in pyproject.toml under [project.scripts] and implemented in olmocr/pipeline.py via the cli_main function.

olmocr --help

This should display the full CLI usage documentation, including options for --markdown, --pdfs, and --server.

Usage Examples

Once installed, you can process documents using the command-line interface that coordinates olmocr/pipeline.py with olmocr/work_queue.py for task distribution.

Process a Single PDF Locally

# Download a sample PDF

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

# Run OCR pipeline

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

Results appear in ./workspace/markdown/sample.md, including LaTeX math and formatted tables generated by the prompt logic in olmocr/prompts/prompts.py.

Connect to a Remote vLLM Server

For setups without local GPU resources, use the remote inference mode:

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

The pipeline forwards each page to the specified server endpoint, avoiding local GPU load while using olmocr/image_utils.py for preprocessing.

Run with Docker

For containerized deployments, use the official image which bundles the 30GB model and all system dependencies:

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"

Summary

• Install system dependencies first: Poppler and fonts are required for PDF rendering in olmocr/image_utils.py.
• Choose your flavor: Use pip install olmocr for remote inference, or pip install "olmocr[gpu]" with CUDA extras for local GPU execution.
• Verify with CLI: Run olmocr --help to confirm the installation correctly linked the entry point defined in pyproject.toml.
• Consider Docker: The alleninstituteforai/olmocr:latest-with-model image provides a complete environment without local dependency management.

Frequently Asked Questions

What Python version does olmOCR require?

olmOCR requires Python 3.11. Create a dedicated Conda environment with conda create -n olmocr python=3.11 to avoid conflicts with other packages, as the dependency chain includes specific versions of PyTorch and transformers that may clash with existing installations.

Do I need a GPU to run olmOCR?

No. You can run olmOCR on CPU-only machines using the remote inference mode (pip install olmocr) which connects to external vLLM servers via the --server flag. However, for local GPU inference, you need an NVIDIA GPU with at least 12GB VRAM and must install the GPU flavor with pip install "olmocr[gpu]".

How do I install olmOCR without CUDA dependencies?

Install the lightweight version with pip install olmocr. This excludes PyTorch, CUDA toolkit, and vLLM from the installation, making it suitable for low-spec machines or client-only setups that use the --server flag to connect to remote inference endpoints defined in olmocr/pipeline.py.

Where is the CLI entry point defined in the source code?

The CLI entry point is defined in pyproject.toml under the [project.scripts] section, pointing to olmocr.pipeline:cli_main. The actual argument parsing and orchestration logic resides in olmocr/pipeline.py, which coordinates with olmocr/work_queue.py for distributed processing and olmocr/image_utils.py for PDF rendering.

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