{"record":{"id":"a68814ce324fc759","repo":"ocrmypdf/OCRmyPDF","slug":"the-rasterizer-pypdfium-option-requires-the-pypd","errorCode":null,"errorMessage":"The --rasterizer pypdfium option requires the pypdfium2 package. Install it with: pip install pypdfium2","messagePattern":"The --rasterizer pypdfium option requires the pypdfium2 package\\. Install it with: pip install pypdfium2","errorType":"validation","errorClass":"MissingDependencyError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/builtin_plugins/pypdfium.py","lineNumber":39,"sourceCode":"\nfrom ocrmypdf import hookimpl\nfrom ocrmypdf.exceptions import MissingDependencyError\nfrom ocrmypdf.helpers import Resolution\n\nlog = logging.getLogger(__name__)\n\n# pypdfium2/PDFium is not thread-safe. All calls to the library must be serialized.\n# See: https://pypdfium2.readthedocs.io/en/stable/python_api.html#incompatibility-with-threading\n# When using process-based parallelism (use_threads=False), each process has its own\n# pdfium instance, so locking is not needed across processes.\n_pdfium_lock = threading.Lock()\n\n\n@hookimpl\ndef check_options(options):\n    \"\"\"Check that pypdfium2 is available if explicitly requested.\"\"\"\n    if options.rasterizer == 'pypdfium' and pdfium is None:\n        raise MissingDependencyError(\n            \"The --rasterizer pypdfium option requires the pypdfium2 package. \"\n            \"Install it with: pip install pypdfium2\"\n        )\n\n\ndef _open_pdf_document(input_file: Path):\n    \"\"\"Open a PDF document using pypdfium2.\"\"\"\n    assert pdfium is not None, \"pypdfium2 must be available to call this function\"\n    return pdfium.PdfDocument(input_file)\n\n\ndef _expand_cropbox_to_mediabox(page) -> None:\n    \"\"\"Set the page's CropBox to its MediaBox so PDFium renders the full page.\n\n    PDFium renders to the CropBox by default. Negative ``crop`` values to\n    ``render()`` are not supported and only pad the output canvas without\n    expanding the rendered area — content outside the CropBox is clipped.\n    The supported approach is to widen the CropBox in memory before rendering.","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/builtin_plugins/pypdfium.py#L21-L57","documentation":"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.","triggerScenarios":"Calling ocr(..., rasterizer='pypdfium') in an environment where `import pypdfium2` fails (not installed).","commonSituations":"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.","solutions":["pip install pypdfium2 (or reinstall ocrmypdf with the pdfium extra).","Or omit rasterizer='pypdfium' to use the default Ghostscript-based rasterizer."],"exampleFix":"$ pip install pypdfium2","handlingStrategy":"validation","validationCode":"if options.rasterizer == 'pypdfium':\n    import pypdfium2  # noqa: F401 — ImportError means missing dep","typeGuard":null,"tryCatchPattern":"from ocrmypdf.exceptions import MissingDependencyError\ntry:\n    ocr(in, out, rasterizer='pypdfium')\nexcept MissingDependencyError:\n    ocr(in, out)  # fall back to default rasterizer","preventionTips":["Declare the pdfium extra in requirements: ocrmypdf[pdfium] or pypdfium2.","Prefer import checks over CLI availability checks for optional deps."],"tags":["ocrmypdf","pypdfium2","missing-dependency","rasterizer"],"backgroundTag":"missing-optional-dependency","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}