Registry / ai-ml / python-doctr

python-doctr

JSON →
library1.0.1pypypi✓ verified 87d ago

docTR (Document Text Recognition) is an open-source Python library leveraging deep learning for high-performance Optical Character Recognition (OCR) on documents. It provides state-of-the-art text detection and recognition for scanned documents, images, and PDFs. Actively maintained by Mindee, it supports multi-language recognition, handwriting, and GPU acceleration, currently at version 1.0.1.

pip install python-doctr
INSTALL
IMPORT
SIG · PYTHON-DOCTR
P
python-doctr
ai-mlpythonv1.0.1
Install
84.7s avg
Import
Disk
5035MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.1 · 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
py 3.103.960 runs
timeout
glibc
py 3.103.960 runs
installs and imports cleanly · install 84.7s · import 0.000s · 6041.6MB
5035MB installed
● package 5035MB
Code
Verified usage

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

DocumentFile
from doctr.io import DocumentFile
ocr_predictor
from doctr.models import ocr_predictor
from_hub
from doctr.models import from_hub
from doctr.models.pre_trained import from_hub
from_hub for Hugging Face models is directly under doctr.models now, not a submodule 'pre_trained'.

This quickstart demonstrates how to load an image, initialize a pre-trained OCR model, and extract text using docTR's core functionality. It leverages `DocumentFile` to handle input and `ocr_predictor` for the end-to-end OCR pipeline.

import os from doctr.io import DocumentFile from doctr.models import ocr_predictor # For demonstration, create a dummy image file if it doesn't exist # In a real scenario, you'd have an actual image or PDF path dummy_image_path = 'sample.png' if not os.path.exists(dummy_image_path): try: from PIL import Image # Create a simple image with text img = Image.new('RGB', (200, 100), color = (255, 255, 255)) from PIL import ImageDraw, ImageFont d = ImageDraw.Draw(img) try: # Try a common font, or fallback font = ImageFont.truetype("arial.ttf", 20) except IOError: font = ImageFont.load_default() d.text((10,10), "Hello docTR!", fill=(0,0,0), font=font) img.save(dummy_image_path) print(f"Created dummy image: {dummy_image_path}") except ImportError: print("Pillow not installed, cannot create dummy image. Please provide a real image file.") print("Skipping quickstart example as no image is available.") dummy_image_path = None if dummy_image_path and os.path.exists(dummy_image_path): # Load your document (image or PDF) # For a PDF: doc = DocumentFile.from_pdf("path/to/your/document.pdf") # For multiple images: doc = DocumentFile.from_images(["path/to/img1.jpg", "path/to/img2.png"]) doc = DocumentFile.from_images(dummy_image_path) # Load a pre-trained OCR model # Since v1.0.0, PyTorch is the default and only backend. model = ocr_predictor(pretrained=True) # Analyze the document result = model(doc) # Print the extracted text content # The result object contains detailed information about words, lines, blocks, and pages. print("\n--- OCR Result ---") for page in result.pages: for block in page.blocks: for line in block.lines: print(" ".join([word.value for word in line.words])) # You can also export the full structured output as JSON # print(result.export()) else: print("Quickstart skipped due to missing image.")
Debug
Known issues
breakingdocTR v1.0.0 removed TensorFlow as a supported backend. The library now exclusively uses PyTorch. Old `python-doctr[tf]` installation options are no longer valid, and training scripts have been updated.
fix
Ensure you have PyTorch installed (`pip install torch torchvision`) and remove any TensorFlow-specific code or installations related to docTR. The base `pip install python-doctr` will now install with PyTorch support by default.
affects: >=1.0.0
gotchaProcessing PDFs or HTML documents with `DocumentFile.from_pdf` or `DocumentFile.from_url` (via `html` extra) often relies on `weasyprint`, which itself has system-level dependencies (e.g., `libglib2.0-0`, `libpango-1.0-0` on Linux) that are not automatically installed by `pip`.
fix
Install `weasyprint`'s system dependencies manually for your OS (e.g., `sudo apt-get install -y libgl1-mesa-glx libglib2.0-0 libpango-1.0-0 libpangoft2-1.0-0` on Ubuntu/Debian). For specific `weasyprint` errors like `OSError: cannot load library 'gobject-2.0-0'`, refer to `weasyprint`'s documentation.
affects: All versions using `weasyprint`
gotchaGPU acceleration requires manually installing `torch` and `torchvision` with CUDA support, which `pip install python-doctr` does not automatically handle to keep the base package lightweight.
fix
Follow PyTorch's official installation guide to install `torch` and `torchvision` with appropriate CUDA versions (e.g., `pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118`) *before* installing `python-doctr` or its `[torch]` extra.
affects: All versions
Errors
Common errors & fixes
OSError: cannot load library 'gobject-2.0-0'
Missing system-level dependencies for `weasyprint`, which is used by docTR's `html` and `viz` extras for PDF/HTML processing.
fix
Install the required system packages. For Debian/Ubuntu: `sudo apt-get install -y libglib2.0-0 libpango-1.0-0 libpangoft2-1.0-0`. Other Linux distributions, macOS, or Windows will have different prerequisites for `weasyprint`.
ModuleNotFoundError: No module named 'doctr.io'
The `python-doctr` library is either not installed, or the Python interpreter in use does not have access to the installed package (e.g., wrong virtual environment).
fix
Ensure `python-doctr` is installed in your active environment: `pip install python-doctr`. If in an IDE like PyCharm, verify the correct Python interpreter is selected for your project.
git clone ... then pip install -e doctr/ fails due to SSL certificate verification issues.
Corporate proxies or misconfigured Git installations can block secure connections (SSL/TLS) when cloning repositories or fetching packages.
fix
Temporarily disable SSL verification for Git: `git config --global http.sslVerify false` *before* cloning. Remember to re-enable it afterwards: `git config --global http.sslVerify true` for security.
Upgrade
Version history
1.0.1latest on PyPI · released Feb 4, 2026
Audit
Dependencies
torchrequiredDeep learning backend (default and only one since v1.0.0)
torchvisionoptionalRequired for GPU acceleration with PyTorch
weasyprintoptionalOptional dependency for HTML document processing and visualization utilities (part of `viz` and `html` extras)
pypdfium2requiredPDF processing backend (required for DocumentFile.from_pdf)
Agent activity
13 hits · last 30 days
node
10
Amazon
1
OpenAI (training)
1
Resources
python-doctr — pip install python-doctr · libregistry