OcrRoute

OcrRoute is an OCR gateway for multi-engine text extraction: one HTTP endpoint in front of local and cloud OCR engines, with routing, load balancing, retries and fallbacks - plus quotas, caching, cost tracking and observability for reliable, cost-aware document understanding. It imports the given AioOCR engine library unchanged (55 OCRPlugin classes: Tesseract, RapidOCR, PaddleOCR, Surya, GOT-OCR, DeepSeek-OCR, Nougat, OCR.Space, Google Vision, Mistral OCR, Gemini/Claude/OpenAI-style VLM OCR, …) in a FastAPI gateway with a web control panel, a desktop app (ManyQt: PyQt5 / PyQt6 / PySide2 / PySide6) and a CLI. Persistence is a single SQLite file.

pip install "ocrroute[local,desktop]"   # from PyPI: core + Tesseract/OpenCV extras + the desktop app
# or, from a clone:
pip install -e ".[local,desktop,dev]"   # core + Tesseract/OpenCV extras + ManyQt + PyQt5 + tests
ocrroute setup                          # admin user, first provider, default route, API key
ocrroute serve                          # API  http://127.0.0.1:20256/v1/docs
                                        # panel http://127.0.0.1:20256/panel/
ocrroute ocr scan.png                   # zero-config OCR through the built-in auto route
ocrroute desktop                        # PyQt5 app (embedded server or remote)

curl -X POST http://127.0.0.1:20256/v1/ocr \
  -H "Authorization: Bearer ocrr_…" \
  -F file=@invoice.pdf \
  -F 'json={"route":"invoices","language":"en","pages":"1-3","output":["json","text","pdf"]}'

The response keeps the engine library's unified result verbatim under result and adds gateway metadata beside it (routing.attempts, routing.explain, usage, artifacts). See docs/API.md.

Screenshots:

Playground: run any engine or route on an image or PDF and inspect the result as text, lines, JSON, routing or ready-to-use code, with the recognised words drawn over the input.

Engines: every detected OCR engine, cloud and local, with availability, capabilities, pricing model, per-engine options, one-click provider creation and a probe button.

What you get:

Several servers:

Run one leader and any number of followers: followers mirror the leader's providers, credentials, routes, API keys and users. Set it up from the web panel (System > Cluster sync) or with .env; see docs/CLUSTER.md.

Editions and more engines:

The stand-alone executables come in two editions:

On Intel Macs the Full edition includes PaddleOCR but not EasyOCR or Surya: PyTorch publishes no Intel-Mac build newer than 2.2, which predates NumPy 2. EasyOCR, Surya and PaddleOCR download their model weights on first use.

Surya is bundled as 0.17.1, the last release that runs OCR entirely in PyTorch; Surya 2 (0.20+) needs a vLLM or llama.cpp server (pip install "ocrroute[surya2]"). Surya's code is Apache-2.0, but its model weights use a modified AI Pubs Open Rail-M license: free for research, personal use and startups under $5M in funding or revenue; other commercial use needs a license from Datalab.

The remaining deep-learning engines (Calamari, keras-ocr, GLM, olmOCR) install on demand in a pip installation: click Install in the Engines page, run ocrroute engines install SuryaOcr, or pip install "ocrroute[surya]". See docs/ENGINES.md.

Documentation:

docs/ARCHITECTURE.md · docs/ROUTING.md · docs/API.md · docs/ENGINES.md · docs/DEPLOYMENT.md · docs/SECURITY.md · docs/TOOLS.md · docs/DECISIONS.md · docs/CHANGELOG.md

Independence note:

Design patterns for gateway routing (fallback chains, balancing strategies, key management, dashboards) are widely used in the ecosystem; OcrRoute applies them to OCR. OcrRoute is an independent Python project with its own namespace (ocrroute, ~/.ocrroute, OCRROUTE_*), its own default port (20256; it refuses to bind 20128), and no chat/completions, LLM proxying or agent-protocol surface. It is not a fork, plugin or companion of any other gateway.

Desktop app and Qt:

The desktop app is written against ManyQt, one API over PyQt4/5/6 and PySide/2/6. The executables ship PyQt5; from source, pip install "ocrroute[desktop]" installs ManyQt with PyQt5, and any other installed binding works too (QT_API=pyqt6, QT_API=pyside6...). ManyQt is GPL-3.0, like PyQt5.

Support the project:

OcrRoute is free and open source. If it saves you time or money, you can support its development:

• ba9chich: https://ba9chich.com/fr/IninouUsama
• Ko-fi: https://ko-fi.com/usamatn

Stars, bug reports and pull requests help too. Thank you!

Third-party assets:

ocrroute/assets/fonts/DejaVuSans.ttf is DejaVu Sans (Bitstream Vera license; see LICENSE-DejaVu.txt next to it), used by PaddleOCR for visualisations.

License:

MIT - see LICENSE.