OCRmyPDF is a Python library and application that adds an invisible OCR text layer to scanned PDF files, making them searchable. It utilizes the Tesseract OCR engine and other external tools to process documents, capable of producing highly optimized and archived-ready (PDF/A) files. The project is actively maintained with frequent updates, typically seeing major version releases annually and minor/patch releases more often.
pip install ocrmypdfVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to use the modern API introduced in OCRmyPDF v17.0.0, which involves passing an `OcrOptions` object to the `ocrmypdf.ocr()` function. This provides better type hinting and argument validation. It includes basic error handling and uses dummy files for immediate runnable testing. Remember that `ocrmypdf` heavily relies on external system dependencies (like Tesseract and Ghostscript) which must be installed separately.
Manually install required system dependencies (Tesseract, Ghostscript/pypdfium2, etc.) for your operating system. Consult the official OCRmyPDF installation documentation for detailed instructions specific to your platform.
Refactor calls to `ocrmypdf.ocr()` to construct and pass an `OcrOptions` instance: `options = OcrOptions(input_file='...', output_file='...', ...); ocrmypdf.ocr(options)`.
Switch from using individual flags like `--force-ocr` to the unified `--mode` argument in both the command-line interface and the Python API's `OcrOptions`.
For parallel processing of multiple PDFs, spawn separate Python processes for each OCRmyPDF task. Consider using `multiprocessing` or running `ocrmypdf` from subprocesses for isolation.
If encountering JPEG corruption, consider using `pypdfium2` as the PDF rasterizer (if compatible with your setup) instead of Ghostscript, or use a Ghostscript version known not to have the bug. `--rasterizer pypdfium2` can be set in `OcrOptions`.
If you intend to re-OCR or process such files, use `--force-ocr` (or `--mode force`), `--skip-text` (or `--mode skip`), or `--redo-ocr` (or `--mode redo`) depending on the desired behavior.
Install Tesseract OCR (e.g., `sudo apt-get install tesseract-ocr` on Debian/Ubuntu, `brew install tesseract` on macOS, or via installer on Windows) and ensure its executable directory is added to your system's PATH.
Ensure Ghostscript is correctly installed and updated on your system. For problematic PDFs, try repairing them first using external tools (e.g., `gs -o output.pdf -dSAFER -sDEVICE=pdfwrite input.pdf`). If using ocrmypdf v17+, consider using `pypdfium2` as an alternative rasterizer if Ghostscript issues persist.
Use `--force-ocr` to force OCR on all pages (rasterizing vector content), `--redo-ocr` to remove existing OCR and re-OCR, or `--skip-text` to pass pages with existing text directly to the output without changes.
Attempt to repair the PDF using external tools like Ghostscript (`gs -o output.pdf -dSAFER -sDEVICE=pdfwrite input.pdf`) or `pdftk`, or obtain a non-corrupt version of the file.