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

> Install olmocr for local or remote inference with pip. Choose lightweight, GPU, Beaker, or benchmark versions for a custom setup. Get started now.

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

---

**You can install olmocr using pip with four different flavors: lightweight remote inference (`pip install olmocr`), local GPU support (`pip install "olmocr[gpu]"`), Beaker cluster integration (`pip install "olmocr[beaker]"`), or benchmark dependencies (`pip install "olmocr[bench]"`), each configured in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) to match your hardware and use case.**

olmocr is an open-source Python OCR toolkit developed by the Allen Institute for AI that converts PDFs, PNGs, and JPEGs into clean Markdown using vision-language models. Whether you need a lightweight client to connect to remote inference servers or a full GPU-accelerated pipeline running locally, the installation process in `allenai/olmocr` supports multiple configurations via optional dependencies defined in the repository's [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml).

## System Prerequisites

Before installing olmocr, you must install system-level dependencies for PDF processing and font rendering. These requirements support the image conversion utilities in [`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py) and the text rendering pipeline.

On Ubuntu/Debian systems, install Poppler and Microsoft fonts:

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

```

Create a fresh Conda environment to avoid dependency conflicts with other packages:

```bash
conda create -n olmocr python=3.11
conda activate olmocr

```

## Installation Methods

The `allenai/olmocr` repository organizes dependencies into optional extras defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml). Choose the flavor that matches your infrastructure and whether you plan to run the **vision-language model** locally or remotely.

### Remote Inference (Lightweight)

Install only the core library if you plan to use an external vLLM server via the `--server` flag. This excludes PyTorch and model files, making it suitable for low-spec machines or distributed clients.

```bash
pip install olmocr

```

This installs the CLI entry point (`olmocr`) implemented in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) and the work queue system in [`olmocr/work_queue.py`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py), but delegates inference to remote endpoints.

### Local GPU Inference

For local execution on NVIDIA GPUs (≥ 12 GB VRAM), install the GPU flavor which includes PyTorch, Transformers, and vLLM dependencies matched to CUDA 12.8.

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

```

Optionally install FlashInfer for faster CUDA inference:

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

```

This configuration enables the full pipeline including the **filtering** logic in [`olmocr/filter/filter.py`](https://github.com/allenai/olmocr/blob/main/olmocr/filter/filter.py) and **prompt generation** in [`olmocr/prompts/prompts.py`](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/prompts.py) to run entirely on your local machine.

### Beaker Execution

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

```bash
pip install "olmocr[beaker]"

```

This adds `beaker-py` and CLI flags for submitting distributed jobs using the Beaker cluster integration.

### Benchmark Suite

To run the comprehensive olmOCR-Bench suite locally (including 7,000+ test cases), install the benchmark dependencies:

```bash
pip install "olmocr[bench]"

```

This pulls in additional packages like `tinyhost`, `playwright`, and `openai` required by the test suite in `olmocr/bench/`.

### Combining Flavors

You can combine multiple extras for complex workflows. For example, to enable both local GPU inference and benchmarking:

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

```

## Verification

Verify your installation by checking the CLI help output, which reflects the argument parsing logic in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py):

```bash
olmocr --help

```

This should display the full usage instructions for the `cli_main` function, including options for `--markdown`, `--pdfs`, and `--server`.

## Docker Installation

For a containerized deployment that includes the complete model (≈ 30 GB) and all system dependencies, use the official Docker 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 approach bundles Poppler, fonts, and the VLLM weights, eliminating the need for local dependency management.

## Summary

- **Install olmocr** via pip with optional extras to match your infrastructure: `pip install olmocr` for remote inference, `pip install "olmocr[gpu]"` for local CUDA execution, or `pip install "olmocr[beaker]"` for cluster jobs.
- **System prerequisites** include Poppler and Microsoft fonts to support PDF rendering in [`olmocr/image_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/image_utils.py).
- **Verification** requires running `olmocr --help` to confirm the CLI entry point from [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) is accessible.
- **Docker** provides a self-contained alternative with the full model weights pre-loaded.

## Frequently Asked Questions

### What Python version does olmocr require?

olmocr requires Python 3.11 for optimal compatibility with its dependencies, particularly the vLLM and PyTorch stack used in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py). Create a dedicated Conda environment with `conda create -n olmocr python=3.11` to avoid conflicts with other packages.

### Can I install olmocr without a GPU?

Yes. Install the lightweight remote inference flavor with `pip install olmocr`, which excludes PyTorch and CUDA dependencies. This configuration relies on the `--server` flag to send images to an external vLLM endpoint, making it suitable for CPU-only machines or low-resource environments.

### Where are the optional dependencies defined in the source code?

All installation flavors and their specific package requirements are declared in the `[project.optional-dependencies]` table of [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) in the repository root. The `[gpu]`, `[beaker]`, and `[bench]` extras map to different subsets of the full dependency graph used by components like [`olmocr/work_queue.py`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py) and [`olmocr/viewer/dolmaviewer.py`](https://github.com/allenai/olmocr/blob/main/olmocr/viewer/dolmaviewer.py).

### How do I run olmocr after installation?

After installation, use the `olmocr` CLI command to process PDFs. For local GPU inference: `olmocr ./workspace --markdown --pdfs document.pdf`. For remote inference, add `--server http://host:8000/v1 --model allenai/olmOCR-2-7B-1025-FP8`. The CLI entry point is defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml) and implemented by the `cli_main` function in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py).