OCR Python library and command line: read a PDF in one call
The OCR Python library ocr-software is one command and one function call. It sends a PDF or scan to the API and writes the result: text, Markdown, hOCR, JSON with a box and a confidence for every word, or a searchable PDF. Which means: a script reads your scans without a line of glue code.
Install the OCR Python library from GitHub
The client is MIT-licensed, needs Python 3.9 or newer and nothing beyond the standard library. The source is public. It is not on PyPI yet, so pip install ocr-software does not work today; install from GitHub:
pip install git+https://github.com/ocr-software/ocr-software-python
export OCR_SOFTWARE_API_KEY=ocr_...
ocr-software scan.pdf -o scan.txt
On the hosted API, the key comes from the order page.
OCR command line: PDF to text, Markdown or searchable PDF
ocr-software --list-pipelines
ocr-software scan.pdf --pipeline scan-ctc@2 --format md -o scan.md
ocr-software scan.pdf --pipeline scan-ctc@2 --format pdf -o searchable.pdf
--list-pipelines needs no key and marks the default. Without --pipeline the client uses the fastest and cheapest available one and names it on stderr, never silently; name a pipeline yourself whenever you want another. --dry-run prints the page count and the price in euros and runs nothing. Formats are text (the default), md, json, hocr and pdf, and the searchable PDF exists only here, because it needs your original file. With -o the file appears whole or not at all.
Python OCR example: read a PDF from a script
from ocr_software import Client
client = Client() # key and address from the environment
text = client.ocr("scan.pdf", "scan-ctc@2", "md")
client.default_pipeline() returns the default; quote is a dry run that returns the page count and the price and runs nothing. submit, wait and result give you the steps one by one. If a page was not read, ocr raises PagesUnread and the partial result is attached.
Exit codes tell a script whether every page was read
| Exit code | Meaning |
|---|---|
0 | Done, every page read. |
1 | Error from the service or the network. A script may retry. |
2 | Wrong call: unreadable input, no key, a bad address. |
3 | The job is done but a page failed; the file is written and incomplete. |
4 | The job did not finish within --timeout; it keeps running. |
Busy or failing answers (429, 500, 502, 503, 504) and network errors are retried with growing pauses, and a submit carries an Idempotency-Key, so a retry never creates a second job or a second charge. The client looks at every file first and refuses anything that is not a PDF, PNG, JPEG or TIFF, or is larger than 100 MiB. The key never appears in an output or an error message, and OCR_SOFTWARE_ALLOWED_DIR limits the folder the client reads from.
Run the OCR Python library against your own server
Set OCR_SOFTWARE_BASE_URL (or --base-url) to the address of your own server, for example http://127.0.0.1:8080; the calls stay the same (install guide). The API guide has the raw HTTP calls behind the client.
Production use, high volume or your own server?
Private use and tests are free. For a company in production, a server of your own or a pipeline built on your pages, send the kind of page and the volume, and get a written offer.
