Skip to main content

torchOCR

A PyTorch-native, end-to-end OCR library — batchable, GPU-first, and free of clunky C++ runtimes.

CI · PyPI · [ python · 3.10+ ] · [ pytorch · 2.0+ ] · docs · [ license · BSD-3-Clause ]


Why torchOCR

Every modern deep learning stack lives in PyTorch — except OCR. The dominant tools (Tesseract, PaddleOCR, EasyOCR) wrap C++ binaries, ship custom runtimes, or stitch together TensorFlow and ONNX detours that fight against PyTorch's batching, autograd, and torch.compile. The result is an ecosystem where reading text from an image is the only thing you can't do natively.

torchOCR is a clean-slate, pure-PyTorch OCR pipeline modeled after torchvision. Detection, recognition, and document-level data structures are first-class nn.Modules and dataclasses. Tensors stay on-device, batches stay batches, and the public API is small enough to read in an afternoon.

Philosophy

  • Pure PyTorch. No Tesseract, no Leptonica, no ONNX intermediaries. Every layer is nn.Module you can subclass, fine-tune, or state_dict-load.
  • PyTorch 2.0 first. Every model FX-traces, torch.exports with dynamic sizes and torch.compiles — checked in CI, shape contracts included (see Graph capture below).
  • Explicit shape contracts. Outputs are typed dataclasses (DBNetOutput), not Dict[str, Tensor]. Every model documents its tensor shapes — and asserts them at runtime.
  • Modular, torchvision-style API. from torchocr.models import DBNet, CRNN. Models compose, swap, and re-export the way you'd expect from torchvision.models.
  • Zero magic at import time. No global state, no monkey-patching, no network calls unless you ask for them.

Installation

pip install torchocr

From source:

git clone https://github.com/BryanBradfo/torchOCR.git
cd torchOCR
pip install -e .

Requires Python 3.10+, PyTorch 2.0+, and torchvision 0.23+.

Quickstart

Image to text in three lines

from torchocr import OCRPipeline, load_image

pipeline = OCRPipeline.from_pretrained(
    detector_weights="DBNet_ResNet18_VD_Weights.ICDAR2015",           # scene text, English
    recognizer_weights="CRNN_ResNet34_VD_Weights.MJSYNTH_ICDAR2015_TOTALTEXT_MLT19",  # Latin scene text
    device="cuda",                                                      # or "cpu" (~4 s/page)
    min_text_score=0.8,                                                 # drop unreadable regions
)
doc = pipeline(load_image("photo.jpg"))
doc.text        # list[str], one per region, in reading order
doc.polygons    # (K, 4, 2) rotated quads, reading order, in input pixels
doc.scores      # (K,) recognition confidence

Each stage brings its own preprocessing (weights.transforms()), post-processing (weights.meta["postprocess"]), charset (weights.meta["charset"]) and decoder (weights.meta["decoder"]: here CTC beam search with a character language model, downloaded on first use); words are rectified out of the original-resolution image with torchocr.ops.crop_quads. The defaults (from_pretrained() with no arguments) pair the multilingual PP-OCRv3 detector with the Chinese + English recognizer, suited to documents.

Building blocks

Every stage is an ordinary module or callable you can use, replace or fine-tune on its own:

import torch
from torchocr import DBPostProcessor, load_charset
from torchocr.decoders import build_decoder
from torchocr.io import load_image
from torchocr.models import CRNN, DBNet, CRNN_ResNet34_VD_Weights, DBNet_ResNet18_VD_Weights
from torchocr.ops import crop_quads

image = load_image("photo.jpg")                                   # (3, H, W) uint8 RGB

det_weights = DBNet_ResNet18_VD_Weights.ICDAR2015
detector = DBNet(weights=det_weights).eval()
batch = det_weights.transforms()(image)[None]                     # (1, 3, H', W'), multiples of 32
with torch.no_grad():
    detection = detector(batch)                                   # DBNetOutput(probability, threshold)
quads = DBPostProcessor(**det_weights.meta["postprocess"]).quadrilaterals(detection)[0]  # (K, 4, 2)
quads = quads * torch.tensor([image.shape[2] / batch.shape[3], image.shape[1] / batch.shape[2]])

rec_weights = CRNN_ResNet34_VD_Weights.MJSYNTH_ICDAR2015_TOTALTEXT_MLT19
recognizer = CRNN(weights=rec_weights).eval()
page = rec_weights.transforms().normalize(image)[None].float()
crops, _ = crop_quads(page, quads, torch.zeros(len(quads), dtype=torch.long), height=32, max_width=320)
with torch.no_grad():
    logits = recognizer(crops)                                    # (T, K, num_classes), CTC-ready
charset = load_charset(rec_weights.meta["charset"], rec_weights.meta["num_classes"])
texts = build_decoder(rec_weights, charset)(logits)               # beam search + character LM

Augmenting text polygons with torchvision.transforms.v2

Text regions travel through torchvision's own v2 transforms as tv_tensors.KeyPoints; torchocr adds the two OCR-specific pieces, a crop that never cuts a word and a sanitizer that keeps texts and ignore aligned with the polygons that survive.

from torchvision.transforms import v2
from torchocr.datasets import TotalText
from torchocr.transforms import MakeDBTargets
from torchocr.transforms.v2 import RandomTextCrop, SanitizeTextPolygons, wrap_sample

augment = v2.Compose([
    v2.RandomRotation(10), v2.RandomAffine(0, scale=(0.5, 3.0)),
    RandomTextCrop(), v2.Resize(size=None, max_size=640),
    SanitizeTextPolygons(),            # off-canvas words dropped, clipped ones marked don't-care
])
image, target = augment(*wrap_sample(*TotalText("~/data/totaltext", split="train")[0]))
db_targets = MakeDBTargets()(target.polygons, target.ignore, image.shape[-2:])

Graph capture: torch.compile, torch.export, FX

Every model is tested (tests/test_compile_export.py) to FX-trace, torch.export and torch.compile, with its runtime shape contract intact:

from torch.export import Dim, export

# Detector: one fused graph, ~1.2x faster on GPU (ResNet18-VD at 736x1280: 25.0 -> 20.3 ms).
detector = torch.compile(DBNet(weights="DBNet_ResNet18_VD_Weights.ICDAR2015").eval(), fullgraph=True)

# Ahead-of-time export with any image size that is a multiple of 32.
side = lambda name: 32 * Dim(name, min=1, max=128)
program = export(DBNet(backbone="resnet18_vd").eval(), (torch.randn(1, 3, 736, 1280),),
                 dynamic_shapes=({2: side("h"), 3: side("w")},))

CRNN exports with a dynamic batch but a static crop width, because torch.export specializes nn.LSTM's sequence length; inference already pads every crop to max_width. Under torch.compile it graph-breaks at the LSTM (a Dynamo limitation), so fullgraph=True applies to the detector only. Compiled outputs match eager to ~1e-3 (Inductor reorders floating-point operations); published metrics are measured in eager mode.

Architecture

Component Module What it is
DBNet torchocr.models Differentiable Binarization detector: ResNet-18-VD + FPN or MobileNetV3-large ×0.5 + RSEFPN backbone, probability and threshold heads. Returns a typed DBNetOutput.
CRNN torchocr.models Convolutional recurrent recognizer: ResNet-34-VD (or VGG-style) CNN, two bidirectional LSTMs, linear classifier. Returns CTC logits (T, B, num_classes).
DBPostProcessor torchocr Probability map → rotated word quads in reading order.
CTCGreedyDecoder, CTCBeamDecoder, CharNGramLM torchocr.decoders CTC decoding, optionally fused with a character language model.
OCRPipeline, DocumentTensor torchocr Composition of the stages; a dataclass holding the input image, texts, quads, boxes and confidences.

Both models enforce their input contracts at runtime (DBNet: (B, 3, H, W) with H, W ≡ 0 (mod 32); CRNN: (B, 3, 32, W)) and raise ValueError with the offending shape.

Status

Capability State
DBNet / CRNN architectures + shape contracts ✅ Implemented
Pretrained weights (*_Weights enums, hash-checked, on Hugging Face) ✅ 4 PaddleOCR conversions + 5 torchocr-trained checkpoints
DB post-processing (contours → rotated quads) ✅ Implemented
torchocr.ops.crop_quads (batched perspective rectification) ✅ Implemented
torchocr.metrics (ICDAR hmean, word accuracy / CER) and torchocr.datasets.ICDAR2015 ✅ Implemented
DB training (references/detection/train.py) ✅ Implemented
CTC greedy and beam-search decoding (character n-gram LM) ✅ Implemented
Datasets: ICDAR-2015, Total-Text, FUNSD, LMDB word crops ✅ Implemented
End-to-end OCRPipeline.from_pretrained (image → text, reading order) ✅ Implemented
Polygon-aware augmentation on torchvision.transforms.v2 (torchocr.transforms.v2) ✅ Implemented
Synthetic pre-training data (MJSynth via Parquet → LMDB) ✅ Implemented
Sphinx documentation site with example gallery (docs/, gallery/) ✅ Implemented

Benchmarks (official IoU protocol, reproducible with references/; fine-tuned weights are the last epoch, thresholds chosen on training splits only):

Detection (test hmean) ICDAR-2015 Total-Text FUNSD
DBNet_ResNet18_VD_Weights.ICDAR2015 (trained by torchocr, 12.4 M params) 0.809 0.696 0.826
DBNet_MobileNetV3_Large_05_Weights.ICDAR2015 (trained by torchocr, 0.6 M params) 0.734
DBNet_MobileNetV3_Large_05_Weights.PPOCR_V3_EN (converted, line-level) 0.441 0.180
Recognition (word accuracy on ground-truth words) ICDAR-2015 Total-Text
CRNN_ResNet34_VD_Weights.MJSYNTH_ICDAR2015_TOTALTEXT_MLT19 + beam search & char LM 0.799 0.819
CRNN_ResNet34_VD_Weights.ICDAR2015_TOTALTEXT_MLT19 + beam search & char LM 0.791 0.802
CRNN_ResNet34_VD_Weights.ICDAR2015 (greedy) 0.738
CRNN_ResNet34_VD_Weights.PPOCR_SERVER_V2 (converted, greedy) 0.665 0.701

End to end (OCRPipeline, image → text; a word counts when detected and read correctly, case-insensitive, generic vocabulary; references/end2end/evaluate.py), with the two bold models and min_text_score=0.8: 0.665 on ICDAR-2015 (0.219 with the converted PaddleOCR weights), 0.585 on Total-Text and 0.722 on FUNSD scanned forms; ~60 ms per street image on a laptop GPU.

weights.meta documents each checkpoint's provenance, license, preprocessing and known limits.

Roadmap

  • Distribution: PyPI release (pip install torchocr) and a hosted documentation site.
  • Detection: detectors pre-trained on SynthText and fine-tuned on curved text (Total-Text is the weakest benchmark).
  • Recognition: an ASCII-only recognizer head and a multilingual variant; an attention/transformer recognizer.
  • Deployment: torch.ao quantization and ONNX / torch.export packaging of both models.

Documentation

Online at https://bryanbradfo.github.io/torchOCR/ (API reference, pretrained weights, benchmarks, example gallery). To build it locally:

pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html   # TORCHOCR_DOCS_GALLERY=0 skips running the examples

Running the tests

pip install -e ".[test]"
pytest

Contributing

Issues and PRs welcome. Each model in src/torchocr/models/ documents its shape contract in the docstring; please match the existing style (from torch import Tensor, nn, Google-style docstrings, Tensor | None unions). See CONTRIBUTING.md for the full coding standards and PR process.

License

BSD 3-Clause, like torchvision — see LICENSE.

Metadata

Release files for torchocr 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for torchocr 0.4.1
File Size Uploaded Provenance Actions
torchocr-0.4.1.tar.gz 114.5 kB With provenance Details for torchocr-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for torchocr 0.4.1
File Interpreter ABI Platform Actions
torchocr-0.4.1-py3-none-any.whl Python 3 none any Details for torchocr-0.4.1-py3-none-any.whl

Total release size: 206.4 kB

Release files / torchocr-0.4.1.tar.gz

Download URL torchocr-0.4.1.tar.gz
Size 114.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e6f935497d40d4997cb5bce1dc6e4861e4c6087f0ac3ec3e57c81a0ec715e3fc
BLAKE2b-256 checksum
How to use checksums
30ef03a898bcc6db8ed3bfc35c736c346809bcfe284f6f1a2fb5fdf0886b93fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / torchocr-0.4.1-py3-none-any.whl

Download URL torchocr-0.4.1-py3-none-any.whl
Size 91.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a46df3828479a284dca2d07e808c5bde1a9c2939ad058d8df0794081630f0a28
BLAKE2b-256 checksum
How to use checksums
84ed41ce86f9f67b879bb16ff7058aac99856e9c82a2f56f34e70d3e87abdec2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for torchocr 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for torchocr-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page