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
muslpy 3.10–3.960 runs
timeout
glibcpy 3.10–3.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.fixEnsure 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`.fixInstall `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.fixFollow 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.
fixInstall 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).
fixEnsure `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.
fixTemporarily 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)