Surya

Last reviewed Aug 26, 2026 · 941 words

On the scanned invoices, photographed receipts and two-column PDFs I have put through it, Surya reads more of the text correctly than Tesseract does, and it tells you where the tables, headings and columns are while it is at it. The price is hardware: the catalogue lists a 4 GB minimum and says a GPU is strongly recommended, and on a CPU-only box a 30-page PDF is a make-a-coffee job rather than a wait-a-second one. Surya is a Python toolkit, not a service. Self-hosting it means wiring it into a pipeline you already own, and the right pipeline is usually Marker.

A toolkit, not a server: where it sits

Surya does 4 things, each as a separate model: text detection (where are the lines), text recognition (what do they say, in 90+ languages), layout analysis (which regions are tables, figures, headers, body text) and reading order. It ships as a pip package with command-line entry points and a Python API, downloads its model weights from Hugging Face on first run, and writes JSON with bounding boxes and text. There is no daemon, no port, no web UI. It belongs inside a script, a worker, or another tool that calls it.

python3 -m venv surya && source surya/bin/activate
pip install surya-ocr
surya_ocr scanned-contract.pdf
surya_layout scanned-contract.pdf

Output lands under a results/ directory as JSON per page, with per-line confidence and coordinates. The first run pulls a few GB of model weights; after that it is offline, which is the whole point for people handling documents they are not allowed to send to Google Cloud Vision or Textract.

Marker is the tool most people actually want

Surya is the engine; Marker, from the same authors at Datalab, is the product built on it. Marker takes a PDF (scanned or born-digital), runs Surya's detection, layout and OCR where needed, and produces clean Markdown with headings, tables and images preserved. If your goal is "turn this pile of PDFs into text a local model can read," Marker is the install, and Surya is what you reach for when you need the raw boxes and regions for something Marker does not do, such as extracting one table's cells with coordinates or building a custom pipeline. Docling is the comparable IBM-backed alternative; try both on 5 of your own documents before choosing, because they fail differently on messy scans.

The downstream step that makes any of this useful is a local model. Marker output piped into Ollama for extraction (vendor, total, due date, as JSON) is a complete, offline document-understanding pipeline on one machine.

Paperless-ngx still speaks Tesseract, and swapping is not a toggle

Paperless-ngx runs OCR through OCRmyPDF, which uses Tesseract, and there is no configuration option that points it at Surya instead. For most office documents Tesseract is adequate and the difference is invisible in search. Where Surya's accuracy matters is poor scans, phone photos, non-Latin scripts and anything with columns or tables, and the practical way to get it is a pre-processing step: run Marker or Surya on the incoming file, attach the resulting text as the document's content through Paperless's API, or run Paperless with OCR skipped for documents you have already processed. That is a small script and a custom consume workflow, not a supported switch. If you never look at the OCR text directly and only search, keep Tesseract and save the GPU.

GPU, CPU and the 4 GB honestly

On an NVIDIA card with 6 GB or more of VRAM, a typical page is a fraction of a second per stage and a 100-page scan is minutes. Apple Silicon works through PyTorch's MPS backend and is usable for personal volumes. CPU-only works, uses the 4 GB of RAM the catalogue names and then some for batches, and is 10 to 50 times slower depending on the box; fine for a nightly batch of 20 documents, painful for a backlog of 5,000. Batch sizes are tunable through environment variables and are the first thing to lower if you see out-of-memory errors. Do not run it inside the same container as your other services; give it its own worker with the GPU passed through.

The licence has two parts

The code is GPL-3.0, which the catalogue flags and which matters only if you redistribute a modified Surya. The model weights carry a separate licence from Datalab that permits free use below a revenue threshold and requires a commercial licence above it. For a homelab or personal archive, neither clause touches you. For a company building a product on it, read the weights licence on the model pages before you ship, because it is the weights, not the GPL, that carry the commercial condition.

What I'd do

Install Marker on the machine with the GPU, run every scanned PDF through it into Markdown, and feed that to a local model for extraction; use Surya directly only when you need coordinates or a single stage. Leave Paperless-ngx on Tesseract for the documents you merely need to find, and route the ones that matter (contracts, anything in a non-Latin script, phone photos) through the Surya path with a short script. On CPU only, run it as a nightly batch and do not expect it to keep up with a scanner in daily use; the document management category has the tools that do that part.