Registry / data / ocrmypdf

ocrmypdf

JSON →
library17.11.0pypypi✓ verified 21d ago

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 ocrmypdf
INSTALL
IMPORT
SIG · OCRMYPDF
O
ocrmypdf
datapythonv17.11.0
Install
8.6s avg
Import
1482ms
Disk
142MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v16.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.556s · 113.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 8.6s · import 1.408s · 104MB
142MB installed
● package 142MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ocr
from ocrmypdf import ocr
OcrOptions
from ocrmypdf import OcrOptions
from ocrmypdf._options import OcrOptions
As of v17.0.0, OcrOptions is exported directly from the top-level 'ocrmypdf' module for cleaner API usage.

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.

import ocrmypdf from ocrmypdf import OcrOptions import os # Create dummy input.pdf for demonstration with open('input.pdf', 'wb') as f: f.write(b'%PDF-1.4\n1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj 2 0 obj<</Type/Pages/Count 1/Kids[3 0 R]>>endobj 3 0 obj<</Type/Page/MediaBox[0 0 612 792]/Contents 4 0 R>>endobj 4 0 obj<</Length 11>>stream\nBT /F1 12 Tf 72 712 Td (Hello World)Tj ET\nendstream\nendobj\nxref\n0 5\n0000000000 65535 f\n0000000009 00000 n\n0000000055 00000 n\n0000000109 00000 n\n0000000171 00000 n\ntrailer<</Size 5/Root 1 0 R>>startxref\n200\n%%EOF') # The recommended way to call ocrmypdf.ocr() is to construct an OcrOptions object. # This provides type hints and validation. (v17.0.0+) options = OcrOptions( input_file='input.pdf', output_file='output_ocr.pdf', deskew=True, languages=['eng'], # Example: use environment variable for Tesseract path if needed for CI/local testing # tesseract_path=os.environ.get('TESSERACT_PATH', None) ) try: ocrmypdf.ocr(options) print("OCR processing complete. Output saved to output_ocr.pdf") except ocrmypdf.exceptions.BadArgs as e: print(f"Error with OCRmyPDF arguments: {e}") except ocrmypdf.exceptions.InputFileError as e: print(f"Error with input file: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: # Clean up dummy files if os.path.exists('input.pdf'): os.remove('input.pdf') if os.path.exists('output_ocr.pdf'): os.remove('output_ocr.pdf')
ocrmypdf --version
Debug
Known issues
breakingOCRmyPDF relies heavily on external system dependencies (e.g., Tesseract OCR, Ghostscript). These are NOT installed by `pip install ocrmypdf` and must be provided by the operating system package manager (e.g., `apt`, `brew`, `choco`). Without them, the library will not function, often resulting in 'file not found' errors.
fix
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.
affects: <=17.x.x
breakingStarting with v17.0.0, the `ocrmypdf.ocr()` function now officially recommends accepting an `OcrOptions` object for all parameters. While the legacy positional argument style is still supported, using `OcrOptions` offers improved type hinting, validation, and clarity.
fix
Refactor calls to `ocrmypdf.ocr()` to construct and pass an `OcrOptions` instance: `options = OcrOptions(input_file='...', output_file='...', ...); ocrmypdf.ocr(options)`.
affects: >=17.0.0
deprecatedAs of v17.0.0, command-line flags like `--force-ocr`, `--skip-text`, and `--redo-ocr` are consolidated under the new `--mode` argument (e.g., `--mode force`, `--mode skip`, `--mode redo`). The old flags remain as silent aliases but are deprecated in favor of `--mode` for clearer API and command-line usage.
fix
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`.
affects: >=17.0.0
gotchaOCRmyPDF maintains global state, meaning only one OCR operation can reliably run per Python process at a time. Attempting parallel `ocrmypdf.ocr()` calls within a single process can lead to unexpected behavior or deadlocks.
fix
For parallel processing of multiple PDFs, spawn separate Python processes for each OCRmyPDF task. Consider using `multiprocessing` or running `ocrmypdf` from subprocesses for isolation.
affects: <=17.x.x
gotchaA known issue with Ghostscript (a key dependency) can lead to JPEG corruption. This warning was updated in v17.4.1 to confirm persistence in Ghostscript 10.7.0.
fix
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`.
affects: >=17.x.x (depending on Ghostscript version)
gotchaRunning OCRmyPDF on a PDF that already contains text (either digital or a hidden OCR layer) will by default raise an error: 'Page already has text!'. This is a safety mechanism.
fix
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.
affects: <=17.x.x
Errors
Common errors & fixes
TesseractNotFoundError: tesseract is not installed or it's not in your PATH
The Tesseract OCR engine, a required external dependency for ocrmypdf, is either not installed on the system or its executable's location is not included in the system's PATH environment variable.
fix
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.
SubprocessOutputError: Ghostscript rasterizing failed
Ghostscript, another external dependency, encountered an error during PDF rasterization, often due to a malformed PDF, an issue with the Ghostscript installation, or resource limitations.
fix
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.
ERROR - 1: page already has text! – aborting (use --force-ocr to force OCR)
ocrmypdf detected that the input PDF page already contains a text layer (either 'born digital' or previously OCR'd) and, by default, will not re-process it to prevent accidental alteration of existing text.
fix
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.
Input file 'filename' is not a valid PDF
The input file provided to ocrmypdf is corrupt, truncated, or not a valid PDF according to `pikepdf`/`libqpdf`, which ocrmypdf uses for validation and repair.
fix
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.
Upgrade
Version history
17.11.0latest on PyPI · released Aug 28, 2026
Audit
Dependencies
fpdf2requiredRequired for text layer rendering in PDFs.
uharfbuzzrequiredRequired for advanced text layer rendering.
pikepdfrequiredCore library for PDF manipulation, developed by the same author.
pypdfium2optionalOptional Python dependency for PDF rasterization, serving as an alternative to Ghostscript. Recommended for best compatibility.
Agent activity
19 hits · last 30 days
node
16
Amazon
1
Resources