doctr
Use python-doctr (docTR) for OCR/KIE inference, document IO/export, model customization, datasets/training/evaluation, CLI helpers, deployment, and troubleshooting.
SKILL.mdskills/repositories/repo-skills/doctr/SKILL.md
GitHubdocTR repo skill
Use this skill when a task involves python-doctr / docTR: document OCR, key information extraction, text detection/recognition, layout or table parsing, docTR datasets, model customization, command-line OCR, optional deployment surfaces, or docTR-specific errors.
This is a router. Keep detailed work in the linked sub-skills and references.
Quick install and import check
Typical install commands:
pip install python-doctr
pip install "python-doctr[viz,html,contrib]" # only when visualization, HTML input, or contrib ONNXRuntime helpers are needed
Minimal import/metadata check:
python - <<'PY'
from importlib.metadata import version
import doctr
from doctr.io import DocumentFile
from doctr.models import ocr_predictor
print("python-doctr", version("python-doctr"), "doctr", doctr.__version__)
print(DocumentFile, ocr_predictor)
PY
Run scripts/doctr_env_check.py for a safe package/CLI/backend diagnostic before debugging installation, optional extras, CUDA/MPS, or entry-point problems.
Route by task
| User task | Read |
|---|---|
End-to-end OCR or KIE with ocr_predictor / kie_predictor, rotation/layout/table flags, device/batch choices, or output sanity checks |
sub-skills/core-ocr-and-kie/SKILL.md |
Loading PDFs/images/URLs/arrays; interpreting Document, Page, KIEDocument, reading order, JSON/text/XML/Markdown/HTML exports, or table grids |
sub-skills/document-io-and-exports/SKILL.md |
Choosing standalone model factories, supported architectures, custom weights, vocabs/whitelists, Hugging Face Hub, ONNX export, half precision, torch.compile, CUDA/MPS |
sub-skills/models-and-customization/SKILL.md |
| Dataset schemas, built-in/custom datasets, synthetic generators, transforms, validation, training/evaluation/latency contracts, metrics, DDP/GPU caveats | sub-skills/datasets-training-and-evaluation/SKILL.md |
Installed doctr-cli, single-document/batch OCR command helpers, output files, parser defaults, and CLI/script troubleshooting |
sub-skills/cli-and-scripts/SKILL.md |
Optional FastAPI/Streamlit/Docker deployment, doctr.contrib, ArtefactDetector, optional extras, or Hugging Face publishing/loading |
sub-skills/deployment-and-contrib/SKILL.md |
Read shared references
- references/package-overview.md for package metadata, dependency extras, public modules, CLI entry point, and evidence-backed scope.
- references/troubleshooting.md for cross-cutting install/import, optional dependency, model-cache, file-format, backend, and routing failures.
- references/repo-provenance.md before deciding whether this skill is current for another checkout or whether to run
refresh-repo-skill.
Operating rules
- Prefer public package APIs and bundled helpers in this skill tree. Do not require future agents to open or run original repo docs, notebooks, scripts, tests, or checkout paths.
- Treat
pretrained=Falseas shape/API smoke mode only; random-weight OCR is not meaningful. - Treat
pretrained=Trueand many default backbones as possible first-use network/cache events. Confirm the user's offline/network policy before running them. - CPU is enough for required package and skill verification. CUDA/MPS are optional acceleration paths unless the user explicitly needs GPU performance, half precision, DDP, or a device-specific issue.
- Install optional extras only for selected tasks:
vizforshow()/interactive plotting,htmlfor URL/HTML input,contribfor ONNXRuntime-backed contrib utilities. - For training/evaluation, validate labels and run one-sample/one-batch checks before launching long jobs. This skill distills training contracts but does not bundle heavyweight training scripts.
- For services, Docker, Hub push, downloads, credentials, or long-running GPU work, stop and confirm permissions/resources before executing.
Common first actions
- OCR a file in Python: use
DocumentFile.from_pdf()orDocumentFile.from_images(), buildocr_predictor(pretrained=True), runresult = predictor(doc), then inspectresult.render()orresult.export(). - Offline API smoke: use the core OCR sub-skill's
ocr_api_smoke.pywith no pretrained weights. - CLI JSON OCR: use
doctr-cli --input_path INPUT --output results.jsonwhen model downloads are allowed; use the bundled CLI helper with--no-pretrainedonly for parser/API smoke. - Validate custom labels: use
sub-skills/datasets-training-and-evaluation/scripts/validate_doctr_labels.pybefore training or evaluation. - Diagnose install/backend: run
scripts/doctr_env_check.py --json.