ocrmypdf/OCRmyPDF · error · MissingDependencyError

The --rasterizer pypdfium option requires the pypdfium2…

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.

Solutions

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

Example fix

$ pip install pypdfium2

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

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

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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• OCR engine does not have language data for the following…
• A worker process lost access to an input file
• A worker process lost access to an input file
• At least one provider is required
• --clean is required for --unpaper-args

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

Appendix: 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)