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

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, 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).

• 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, 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 (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:

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:

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:

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:

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).

Advanced Configuration Options

Connecting to Remote vLLM Servers

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

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 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 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, 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). Use the latter when debugging inside an interactive container session.

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