OCR a PDF with the Shell Tool
Run OCR on a PDF directly from the command line with the Pdftools SDK Shell Tool. The Shell Tool sends pages to an OCR engine and writes a new PDF with an invisible, selectable text layer while preserving the visual appearance of the document.
The Shell Tool exposes the same OCR module as the SDK. For an overview of how the OCR module processes a document and the three processing dimensions (image OCR, text OCR, page OCR), refer to OCR with the Pdftools SDK.
The OCR command requires a running Pdftools OCR Service instance. For installation details, review Set up Pdftools OCR Service with Pdftools SDK.
- Download and unpack the Pdftools SDK Shell Tool.
- Initialize the Pdftools SDK license. Pass your license key with
-lk "YOUR_LICENSE_KEY"to remove the watermark from the output. Include the less-than (<) and greater-than (>) signs. - Start a Pdftools OCR Service instance. The default endpoint is
http://localhost:7982/.
Command syntax
pdf <input.pdf> ocr -ocr service[@<url>[;<url>...]] [options] <output.pdf>
The minimal invocation is:
pdf in.pdf ocr -ocr service -oim updateText out.pdf
This sends in.pdf to a local OCR Service at http://localhost:7982/ and writes a searchable copy to out.pdf. To connect to a different host, append the URL after service@:
pdf in.pdf ocr -ocr service@http://ocr.example.com:7982/ -oim updateText out.pdf
To distribute load across multiple OCR Service instances, separate URLs with a semicolon:
pdf in.pdf ocr -ocr "service@http://host1:7982/;http://host2:7982/" -oim updateText out.pdf
Engine options
The Pdftools SDK Shell Tool supports a single OCR engine, service, which delegates recognition to a Pdftools OCR Service instance.
| Option | Description |
|---|---|
-ocr <engine> | Select an OCR engine. Supported: service[@<url>[;<url>...]]. Without a URL, the Shell Tool connects to http://localhost:7982/. |
-ocl <languages> | Set OCR recognition languages as a comma-separated string, for example -ocl "German,English". |
-ocp <params> | Pass engine-specific recognition parameters as semicolon-separated key-value pairs, for example -ocp "PredefinedProfile=Default" or -ocp "Profile=/path/to/custom-profile.ini". |
Image OCR options
Image OCR recognizes text in scanned images and adds an invisible text layer. For mode descriptions and use-case guidance, refer to Image OCR.
Mode values are case-insensitive (UpdateText and updateText are equivalent). The tables on this page use the same UpperCamelCase form as the SDK enums.
| Option | Description |
|---|---|
-oim <mode> | Image OCR mode: None (default), UpdateText, ReplaceText, RemoveText, IfNoText. |
-oca | Rotate the scan according to the rotation detected by the OCR engine. |
-occs | Deskew the scan according to the skew angle detected by the OCR engine. |
-otr3 | When -oim is ReplaceText or RemoveText, remove only invisible OCR text (text rendering mode 3) and preserve other text. |
Text OCR options
Text OCR fixes non-extractable text in born-digital PDFs by determining the correct Unicode values for characters whose fonts lack proper mappings. For mode descriptions, refer to Text OCR.
| Option | Description |
|---|---|
-otm <mode> | Text OCR mode: None (default), Update, Replace. |
-ots <skip> | Skip text by font category. Values: None (default), KnownSymbolic, PrivateUseArea. Combine flags with commas, for example -ots "KnownSymbolic,PrivateUseArea". |
-otu <source> | Additional Unicode mapping sources. Values: None (default), InstalledFont, KnownSymbolicPua, FallbackAllPua. Combine flags with commas, for example -otu "InstalledFont,KnownSymbolicPua". |
Page OCR options
Page OCR processes entire pages and adds OCR results as page text. It can also add PDF tagging for accessibility compliance. For mode descriptions, refer to Page OCR.
| Option | Description |
|---|---|
-opm <mode> | Page OCR mode: None (default), All, IfNoText, AddResults. |
-tm <mode> | Tagging mode: Auto (default), None, Update. Adds PDF structure tags for accessibility. |
General options
| Option | Description |
|---|---|
-ocd <d> <d1> <d2> | OCR resolution in DPI. <d> is the default, <d1> the minimum, <d2> the maximum. The values must satisfy d1 <= d <= d2. |
-pef | Process embedded PDF files recursively. |
Examples
Make a scanned document searchable
Apply OCR to scanned images with default options. The OCR engine connects to http://localhost:7982/ and uses English by default:
pdf in.pdf ocr -ocr service -oim updateText -ocl English out.pdf
Combine image, text, and page OCR
Run all three processing dimensions in a single pass to recognize scanned images, fix non-extractable text, and add accessibility tagging:
pdf in.pdf ocr \
-ocr service \
-ocl "German,English" \
-oim updateText \
-otm update \
-opm ifNoText \
-tm Auto \
out.pdf
Adjust OCR resolution
Set the resolution range used to render pages for the OCR engine. Pages are rendered at the default DPI when possible and clamped between the minimum and maximum:
pdf in.pdf ocr -ocr service -oim updateText -ocd 300 200 600 out.pdf
Process embedded files
Apply OCR to embedded PDF files alongside the main document:
pdf in.pdf ocr -ocr service -oim updateText -pef out.pdf
Chain OCR with other commands
The Shell Tool chains commands with :. For example, OCR a scanned document and then convert it to PDF/A-2b in a single invocation:
pdf in.pdf ocr -ocr service -oim updateText : convert -pdfa pdfa-2b out.pdf
Related topics
- OCR with the Pdftools SDK: overview, processing dimensions, and use cases.
- OCR a PDF document: equivalent walkthrough using the SDK in .NET, Java, Python, and C.
- OCR best practices: performance, thread safety, and resource management guidance.
- Pdftools SDK Shell Tool: installation, licensing, and command chaining.