ocrmypdf/OCRmyPDF · error · MissingDependencyError

The --rasterizer pypdfium option requires the pypdfium2 pack

Error message

The --rasterizer pypdfium option requires the pypdfium2 package. Install it with: pip install pypdfium2

What it means

The optional pypdfium rasterizer backend is only used when explicitly requested, and the pypdfium2 import is optional. If options.rasterizer == 'pypdfium' but the package isn't installed, check_options() raises MissingDependencyError with install instructions.

Source

Thrown at src/ocrmypdf/builtin_plugins/pypdfium.py:39

from ocrmypdf import hookimpl
from ocrmypdf.exceptions import MissingDependencyError
from ocrmypdf.helpers import Resolution

log = logging.getLogger(__name__)

# pypdfium2/PDFium is not thread-safe. All calls to the library must be serialized.
# See: https://pypdfium2.readthedocs.io/en/stable/python_api.html#incompatibility-with-threading
# When using process-based parallelism (use_threads=False), each process has its own
# pdfium instance, so locking is not needed across processes.
_pdfium_lock = threading.Lock()


@hookimpl
def check_options(options):
    """Check that pypdfium2 is available if explicitly requested."""
    if options.rasterizer == 'pypdfium' and pdfium is None:
        raise MissingDependencyError(
            "The --rasterizer pypdfium option requires the pypdfium2 package. "
            "Install it with: pip install pypdfium2"
        )


def _open_pdf_document(input_file: Path):
    """Open a PDF document using pypdfium2."""
    assert pdfium is not None, "pypdfium2 must be available to call this function"
    return pdfium.PdfDocument(input_file)


def _expand_cropbox_to_mediabox(page) -> None:
    """Set the page's CropBox to its MediaBox so PDFium renders the full page.

    PDFium renders to the CropBox by default. Negative ``crop`` values to
    ``render()`` are not supported and only pad the output canvas without
    expanding the rendered area — content outside the CropBox is clipped.
    The supported approach is to widen the CropBox in memory before rendering.

View on GitHub (pinned to 5074a0b0e1)

Solutions

pip install pypdfium2 (or reinstall ocrmypdf with the pdfium extra).
Or omit rasterizer='pypdfium' to use the default Ghostscript-based rasterizer.

Example fix

$ pip install pypdfium2

Defensive patterns

Strategy: validation

Validate before calling

if options.rasterizer == 'pypdfium':
    import pypdfium2  # noqa: F401 — ImportError means missing dep

Try / catch

from ocrmypdf.exceptions import MissingDependencyError
try:
    ocr(in, out, rasterizer='pypdfium')
except MissingDependencyError:
    ocr(in, out)  # fall back to default rasterizer

Prevention

Declare the pdfium extra in requirements: ocrmypdf[pdfium] or pypdfium2.
Prefer import checks over CLI availability checks for optional deps.

When it happens

Trigger: Calling ocr(..., rasterizer='pypdfium') in an environment where `import pypdfium2` fails (not installed).

Common situations: Environments where ocrmypdf was installed without the extra (e.g. pip install ocrmypdf instead of ocrmypdf[pdfium,pdf]); deploying to a fresh container without requirements pinned.

Related errors

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/a68814ce324fc759. Report an issue: GitHub.