# How to Run olmOCR Using Docker: A Complete Guide to PDF OCR Containerization

> Run olmOCR with Docker to OCR PDFs. Pull the image, mount your files, and use GPUs for fast PDF to markdown conversion without local setup.

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

---

**Pull the `alleninstituteforai/olmocr:latest-with-model` image, mount your PDF directory to `/workspace`, and run the container with `--gpus all` to convert PDFs to markdown without installing dependencies locally.**

The allenai/olmocr repository provides official Docker images that package the complete olmOCR PDF-to-markdown pipeline, including Python 3.12, poppler utilities, fonts, and vLLM. Using Docker eliminates manual installation of complex GPU libraries and ensures consistent execution across development and production environments.

## Available Docker Images for olmOCR

olmOCR maintains two distinct images in the `alleninstituteforai/olmocr` registry, each targeting different deployment scenarios and defined in the repository's root directory.

### Base Image (`latest`)

Built from the [`Dockerfile`](https://github.com/allenai/olmocr/blob/main/Dockerfile), this image contains the complete runtime environment but excludes the machine learning model. The build process installs system packages (poppler-utils, fonts, git, curl), Python 3.12, and the `olmocr` Python package using `uv pip install --system ".[bench]"` as specified in [[`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml)](https://github.com/allenai/olmocr/blob/main/pyproject.toml).

- **Size**: ~4 GB
- **Startup behavior**: Downloads the model on first use
- **Best for**: Development environments, custom model testing, or scenarios where storage space is constrained

### Pre-bundled Model Image (`latest-with-model`)

This image extends the base via [`Dockerfile.with-model`](https://github.com/allenai/olmocr/blob/main/Dockerfile.with-model), which adds a `RUN` step that downloads the default model (`allenai/olmOCR-2-7B-1025-FP8`) into `/opt/models/hub` before the image is finalized.

- **Size**: ~30 GB
- **Startup behavior**: Ready for immediate inference
- **Best for**: Production deployments, CI/CD pipelines, and users requiring immediate processing without download delays

## Prerequisites for Running olmOCR in Docker

Before executing containers, ensure your system meets these requirements:

1. **NVIDIA GPU support**: The container requires GPU access for the underlying vLLM inference server. You must run with `--gpus all` (or specify particular GPU devices).
2. **NVIDIA Container Toolkit**: Your Docker daemon must support the NVIDIA runtime to expose GPUs to containers.
3. **Storage allocation**: Reserve 4 GB for the base image or 30 GB for the model-included variant, plus additional space for input PDFs and output files.

## Running olmOCR Docker Containers

The container's entrypoint is overridden to `/bin/bash` in the [`Dockerfile`](https://github.com/allenai/olmocr/blob/main/Dockerfile) (lines 58-59), allowing you to pass arbitrary commands to the `olmocr` CLI or start interactive shells.

### Processing a Single PDF

Mount your current working directory to `/workspace` inside the container and specify the output path along with the input PDF:

```bash
docker run --gpus all \
  -v "$(pwd)":/workspace \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /workspace/output --markdown --pdfs /workspace/sample.pdf"

```

This command creates a `/workspace/output` directory on your host containing the markdown conversion of `sample.pdf`.

### Batch Processing Multiple PDFs

For processing entire directories, mount separate volumes for input and output:

```bash
docker run --gpus all \
  -v /path/to/pdfs:/input \
  -v /path/to/output:/output \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /output --markdown --pdfs /input/*.pdf"

```

### Using the Smaller Base Image

If you prefer the ~4 GB image and accept the one-time model download:

```bash
docker pull alleninstituteforai/olmocr:latest
docker run --gpus all \
  -v "$(pwd)":/workspace \
  alleninstituteforai/olmocr:latest \
  -c "olmocr /workspace/output --markdown --pdfs /workspace/sample.pdf"

```

The model downloads automatically on first use and caches for subsequent runs.

### Interactive Debugging Mode

To explore the container environment or test commands manually:

```bash
docker run -it --gpus all alleninstituteforai/olmocr:latest-with-model

```

Once inside, you can run `olmocr --help` or invoke the pipeline directly using `python -m olmocr.pipeline`, which is equivalent to the `olmocr` CLI command as implemented in [[`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py).

## Advanced Configuration Options

### Connecting to Remote vLLM Servers

To avoid running the local inference server inside the container, specify an external vLLM endpoint:

```bash
docker run --gpus all \
  -v "$(pwd)":/workspace \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /workspace/output --server http://my-vllm:8000/v1 --model allenai/olmOCR-2-7B-1025-FP8 --markdown --pdfs /workspace/*.pdf"

```

This configuration skips local model loading and routes all inference requests to the specified server, reducing VRAM requirements within the container.

### Understanding the Build Process

The base image defined in [`Dockerfile`](https://github.com/allenai/olmocr/blob/main/Dockerfile) installs system-level PDF processing dependencies including poppler-utils and font packages. It then installs the Python package using `uv` for faster dependency resolution. The "with-model" variant in [`Dockerfile.with-model`](https://github.com/allenai/olmocr/blob/main/Dockerfile.with-model) executes a download step that populates `/opt/models/hub` with the default model weights before the image is finalized, ensuring the container starts with all necessary artifacts.

## Summary

- olmOCR provides two Docker images: a **4 GB base image** (`latest`) that downloads models on demand, and a **30 GB pre-bundled image** (`latest-with-model`) for immediate execution.
- Both images require **GPU access** via `--gpus all` and expect a **mounted workspace** at `/workspace` or custom paths.
- The container uses `/bin/bash` as its entrypoint, enabling direct invocation of the `olmocr` CLI or interactive shell access.
- For production deployments, use the `latest-with-model` tag to eliminate download latency; for development or custom model testing, use the base `latest` tag.
- All Dockerfiles and build configurations are available in the allenai/olmocr repository under `Dockerfile` and `Dockerfile.with-model`.

## Frequently Asked Questions

### Why is the olmOCR Docker image 30 GB when using latest-with-model?

The `latest-with-model` tag includes the complete FP8 quantized model weights (`allenai/olmOCR-2-7B-1025-FP8`) stored in `/opt/models/hub`, which accounts for roughly 26 GB of the total image size. This eliminates the startup delay for downloading the model but requires significantly more disk space than the base 4 GB image.

### Can I run olmOCR Docker without a GPU?

No. The olmOCR pipeline relies on vLLM for inference, which requires NVIDIA GPU acceleration. You must launch the container with the `--gpus all` flag (or specific GPU device mappings) and have the NVIDIA Container Toolkit installed on your host system.

### How do I process files stored in AWS S3 using the olmOCR container?

Mount an S3-mounted directory or local cache to the container's workspace volume. For example, if using `s3fs` or similar tools on your host, mount the local mountpoint to `/workspace` in the container: `-v /mnt/s3-bucket:/workspace`. The `olmocr` CLI within the container can then access these files via the standard filesystem path.

### What is the difference between `olmocr` and `python -m olmocr.pipeline` commands?

They are functionally identical. The `olmocr` command is a convenience entrypoint installed by the package defined in [`pyproject.toml`](https://github.com/allenai/olmocr/blob/main/pyproject.toml), while `python -m olmocr.pipeline` explicitly invokes the pipeline module located at [[`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py). Use the latter when debugging inside an interactive container session.