Installation#

docTR is distributed on PyPI as python-doctr. It requires Python 3.11 or newer and installs PyTorch as its deep learning backend.

Install the package#

pip

pip install python-doctr

uv

uv add python-doctr
# or, outside of a uv project
uv pip install python-doctr

From source

Install the latest development version, e.g. to try a feature that is not released yet:

pip install "python-doctr @ git+https://github.com/mindee/doctr.git"

To check that everything works, print the installed version:

python -c "import doctr; print(doctr.__version__)"

Note

The pretrained weights are not part of the package: each model is downloaded the first time you use it and cached in ~/.cache/doctr (see Configuration to change this location or to run offline).

Optional extras#

The core package is kept light. A few features need extra dependencies, which you can pull in with extras:

Extra	Installs	Needed for
`viz`	`matplotlib`, `mplcursors`	Displaying predictions with `Document.show()`
`html`	`weasyprint`	Reading web pages with `DocumentFile.from_url()`
`contrib`	`onnxruntime`	The artefact detector of the `contrib` module

# One extra
pip install "python-doctr[viz]"
# Several extras
pip install "python-doctr[viz,html,contrib]"

WeasyPrint system libraries

The html extra relies on WeasyPrint, which needs Pango on the system. On Debian/Ubuntu: sudo apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0. On macOS: brew install pango.

GPU support#

docTR runs on whatever device PyTorch supports. The default torch wheel from PyPI already supports NVIDIA GPUs on Linux; for another CUDA version, ROCm or a CPU-only build, install PyTorch first by following the official selector, then install docTR:

# Example: CPU-only build of PyTorch (smaller download)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install python-doctr

Check which accelerator PyTorch sees:

import torch

print("CUDA:", torch.cuda.is_available())
print("Apple MPS:", torch.backends.mps.is_available())

Models run on the CPU until you move them: see Performance to run them on a GPU or in half precision.

Docker images#

Ready-to-use images with docTR preinstalled are published on the GitHub Container Registry. They are GPU-ready (CUDA 12.2):

docker run -it --gpus all ghcr.io/mindee/doctr:<tag> bash

Pick a <tag> from the registry; Docker explains the tag naming scheme and how to build your own image.

Development installation#

To contribute to docTR, clone the repository and install it in editable mode with all the development tools:

git clone https://github.com/mindee/doctr.git
cd doctr
pip install -e ".[dev]"
pre-commit install

See the contribution guide for the tests, the code style and how to build this documentation.

Next steps#

Quickstart

Extract the text of your first document.

Quickstart

Core concepts

Understand predictors, documents and coordinates.

Core concepts