Registry / ai-ml / surya-ocr

surya-ocr

JSON →
library0.20.0pypypi✓ verified 80d ago

Surya OCR is a Python library offering state-of-the-art optical character recognition (OCR), document layout analysis, reading order detection, and table recognition for over 90 languages. It's built on deep learning models, providing high accuracy for complex document structures. The current version is 0.17.1, and it undergoes active development with frequent releases.

pip install surya-ocr
INSTALL
IMPORT
SIG · SURYA-OCR
S
surya-ocr
ai-mlpythonv0.20.0
Install
85.1s avg
Import
Disk
5197MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.20.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 97.3s
py 3.11
✕ build_error
✓ 88.54s
py 3.12
✕ build_error
✓ 79.03s
py 3.13
✕ build_error
✓ 75.51s
py 3.9
✕ build_error
✕ timeout
5197MB installed
● package 5197MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SuryaOCR
import surya
from surya import SuryaOCR

This quickstart demonstrates how to initialize the Surya OCR model and perform OCR on a dummy image. The `SuryaOCR.create_model()` call will automatically download the necessary deep learning models on its first execution. It performs detection, recognition, and layout analysis to return structured text and bounding boxes. Ensure you have `pillow` installed for image handling.

import asyncio from surya.model.surya import SuryaOCR from PIL import Image as PILImage, ImageDraw, ImageFont # Create a dummy image for demonstration def create_dummy_image(): img = PILImage.new('RGB', (800, 600), color = 'white') d = ImageDraw.Draw(img) try: fnt = ImageFont.truetype("arial.ttf", 40) except IOError: fnt = ImageFont.load_default() d.text((50,50), "Hello, Surya OCR!", fill=(0,0,0), font=fnt) d.text((50,150), "This is a test document.", fill=(0,0,0), font=fnt) return img async def main(): print("Loading Surya OCR models...") # This will download models on first run model = SuryaOCR.create_model() print("Models loaded. Creating dummy image...") image = create_dummy_image() print("Running OCR...") # Run OCR (detection, recognition, and layout) # For real use, replace [image] with a list of PIL.Image objects results = await model.ocr([image], languages=["en"]) print("OCR Results:") for page in results: for line in page.text_lines: print(f" Line: '{line.text}', Bbox: {line.bbox}") # Optional: Print words # for word in page.words: # print(f" Word: '{word.text}', Bbox: {word.bbox}") if __name__ == "__main__": asyncio.run(main())
surya_ocr --version
Debug
Known issues
breakingVersion 0.17.0 introduced a new architecture for the layout model. While high-level APIs might remain compatible, internal behavior, performance characteristics, and potentially the exact structure or interpretation of layout-specific outputs could have changed. If you relied on specific nuances of the previous layout model, verify your results.
fix
Thoroughly test existing code against the new version. Consult release notes and documentation for any API or output changes related to layout analysis. Retrain or re-evaluate any custom post-processing logic.
affects: >=0.17.0
gotchaSurya OCR models are deep learning models and require significant computational resources for optimal performance. CPU-only inference can be very slow, especially for large documents or batch processing. GPU acceleration via `onnxruntime-gpu` and a compatible CUDA setup is highly recommended.
fix
Install `surya-ocr[gpu]` if you have a CUDA-enabled GPU and ensure your CUDA toolkit is correctly set up. Verify `onnxruntime-gpu` is indeed being utilized (e.g., by monitoring GPU usage).
affects: All
gotchaThe necessary deep learning models are downloaded on the first invocation of `SuryaOCR.create_model()` (or similar model loading functions). This initial download requires an internet connection and can take several minutes depending on network speed and model size.
fix
Ensure an active internet connection during the first run. For production environments or air-gapped systems, consider pre-downloading and packaging models if the library supports it (check advanced documentation) or running an initial setup script in a connected environment.
affects: All
gotchaSurya-ocr requires Python version >= 3.10 and < 4.0. Using an incompatible Python version will lead to installation failures or runtime errors.
fix
Ensure your Python environment is within the specified range. Use tools like `pyenv` or `conda` to manage multiple Python versions if needed.
affects: All
Upgrade
Version history
0.20.0latest on PyPI · released May 27, 2026
Audit
Dependencies
torchrequiredCore deep learning framework for models.
transformersrequiredUtilized for transformer-based models.
PillowrequiredImage processing library.
onnxruntimerequiredRuntime for ONNX models (CPU acceleration).
onnxruntime-gpuoptionalRecommended for significantly faster inference on compatible CUDA-enabled GPUs.
Agent activity
41 hits · last 30 days
node
40
OpenAI (training)
1
Resources
surya-ocr — pip install surya-ocr · libregistry