OCRmyPDF AppleOCR
November 3, 2025 · View on GitHub
A plugin for OCRmyPDF that enables optical character recognition (OCR) using the text detection capabilities of Apple’s Vision Framework on macOS.
Apple’s proprietary OCR implementation provides excellent accuracy and speed compared to other on-device OCR engines such as Tesseract.
Installation
The package is available on PyPI.
pip install ocrmypdf-appleocr
Usage
To use the plugin, pass the --plugin option when invoking ocrmypdf. You can also specify the language(s) for OCR using the -l or --language option. If you want to enable automatic language detection, use und (undetermined) as the language code.
ocrmypdf -l jpn --plugin ocrmypdf_appleocr input.pdf output.pdf
Options
--appleocr-recognition-mode: Recognition mode for Apple Vision OCR. Choices:fast,accurate, orlivetext. Default:livetexton macOS 13 and later,accurateon macOS 12 and earlier.--appleocr-disable-correction: Disable language correction in Apple Vision OCR (default:False)--pdf-renderer: Renderer used to embed OCR results as invisible (“phantom”) text. Choices:hocr,sandwich. Default:sandwich.-lor--language: Specify OCR language(s) in ISO 639-2 three-letter codes. Useundfor undetermined language. Specifying multiple languages joined with+(e.g.eng+fra) for multilingual documents is not supported.
Automatic language detection (und) is not supported in livetext mode.
Recognition Modes
The fast and accurate modes use VNRecognizeTextRequest from Apple's Vision framework.
The livetext mode uses the newer ImageAnalyzer API from the VisionKit framework.
Although officially Swift-only, it can be accessed via private API (VKCImageAnalyzer) through pyobjc.
The key difference is that LiveText supports vertical text layout in East Asian languages, which is not handled properly by the older API.
PDF Renderers
This plugin supports two OCRmyPDF renderers: hocr and sandwich.
The default is sandwich.
- sandwich: The plugin renders OCR output as a PDF layer with invisible text, which OCRmyPDF then merges with the original page image.
- hocr: The plugin outputs OCR results as hOCR markup, and OCRmyPDF converts the markup to PDF.
Because the hOCR format cannot represent vertical text in East Asian (CJK) scripts, the hocr renderer cannot accurately reproduce vertical text layouts.
However, OCRmyPDF’s built-in hOCR-to-PDF conversion is more mature and may perform better in other scenarios.
Supported Languages
As of macOS Tahoe 26, the following languages are supported by Apple Vision OCR:
| Language code | Language name | Fast mode | Accurate mode | LiveText |
|---|---|---|---|---|
| eng | English | ✓ | ✓ | ✓ |
| fra | French | ✓ | ✓ | ✓ |
| ita | Italian | ✓ | ✓ | ✓ |
| deu | German | ✓ | ✓ | ✓ |
| spa | Spanish | ✓ | ✓ | ✓ |
| por | Portuguese | ✓ | ✓ | ✓ |
| chi_sim | Chinese (Simplified) | ✓ | ✓ | |
| chi_tra | Chinese (Traditional) | ✓ | ✓ | |
| yue_sim | Cantonese (Simplified) | ✓ | ✓ | |
| yue_tra | Cantonese (Traditional) | ✓ | ✓ | |
| kor | Korean | ✓ | ✓ | |
| jpn | Japanese | ✓ | ✓ | |
| rus | Russian | ✓ | ✓ | |
| ukr | Ukrainian | ✓ | ✓ | |
| tha | Thai | ✓ | ✓ | |
| vie | Vietnamese | ✓ | ✓ | |
| ara | Arabic | ✓ | ✓ | |
| ars | Arabic (Najdi) | ✓ | ✓ | |
| tur | Turkish | ✓ | ✓ | |
| ind | Indonesian | ✓ | ✓ | |
| ces | Czech | ✓ | ✓ | |
| dan | Danish | ✓ | ✓ | |
| nld | Dutch | ✓ | ✓ | |
| nor | Norwegian | ✓ | ✓ | |
| nno | Norwegian (Nynorsk) | ✓ | ✓ | |
| nob | Norwegian (Bokmål) | ✓ | ✓ | |
| msa | Malay | ✓ | ✓ | |
| pol | Polish | ✓ | ✓ | |
| ron | Romanian | ✓ | ✓ | |
| swe | Swedish | ✓ | ✓ |
Acknowledgements
This project incorporates and references code from the following projects:
- straussmaximilian/ocrmac - for invoking
VKCImageAnalyzer(LiveText API) viapyobjc - ocrmypdf/OCRmyPDF-EasyOCR - for PDF rendering of recognized text