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

> Learn to run olmOCR from the command line with this guide. Process PDFs locally or remotely using the allenai/olmocr CLI for efficient OCR.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: how-to-guide
- Published: 2026-07-07

---

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

```bash
pip install olmocr[gpu]

```

For lightweight installation (remote inference only):

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

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

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

```

### Remote Inference

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

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

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

1. **Argument Parsing**: `argparse` builds a configuration object (see line 1199 in [`pipeline.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py)
4. **Worker Processing**: Each worker (default 20) executes the pipeline:
   - Downloads PDFs via utilities in [`olmocr/s3_utils.py`](https://github.com/allenai/olmocr/blob/main/olmocr/s3_utils.py)
   - Optionally filters documents using [`olmocr/filter/filter.py`](https://github.com/allenai/olmocr/blob/main/olmocr/filter/filter.py)
   - Renders pages to base-64 PNGs via [`olmocr/data/renderpdf.py`](https://github.com/allenai/olmocr/blob/main/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:

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

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

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