Installation
To use Docling, simply install docling from your Python package manager, e.g. pip:
pip install docling
uv add docling
Works on macOS, Linux, and Windows, with support for both x86_64 and arm64 architectures.
Alternative PyTorch distributions
The Docling models depend on the PyTorch library.
Depending on your architecture, you might want to use a different distribution of torch.
For example, you might want support for different accelerators or for a CPU-only version.
All the different ways for installing torch are listed on their website https://pytorch.org/.
One common situation is the installation on Linux systems with cpu-only support. In this case, we suggest the installation of Docling with the following options:
# Example for installing on the Linux cpu-only version
pip install docling --extra-index-url https://download.pytorch.org/whl/cpu
For uv users, add the PyTorch CPU index to your pyproject.toml:
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
Then pin torch to that index:
[tool.uv.sources]
torch = [{ index = "pytorch-cpu" }]
Then run:
uv add docling
Installation on macOS Intel (x86_64)
When installing Docling on macOS with Intel processors, you might encounter errors with PyTorch compatibility. This happens because newer PyTorch versions (2.6.0+) no longer provide wheels for Intel-based Macs.
If you're using an Intel Mac, install Docling with compatible PyTorch Note: PyTorch 2.2.2 requires Python 3.12 or lower. Make sure you're not using Python 3.13+.
# For uv users
uv add torch==2.2.2 torchvision==0.17.2 docling
# For pip users
pip install "docling[mac_intel]"
# For Poetry users
poetry add docling
Available extras
The docling package is designed to offer a working solution for the Docling default options.
Some Docling functionalities require additional third-party packages and are therefore installed only if selected as extras (or installed independently).
The following table summarizes the extras available in the docling package. They can be activated with:
pip install "docling[NAME1,NAME2]"
| Extra | Description |
|---|---|
audio |
Installs the Whisper backends for running the ASR pipeline. |
asr |
Installs all inline ASR engines (Whisper, Transformers, and mlx-audio). Needs macOS 14 or later on Apple Silicon. See Processing audio and video. |
vlm |
Installs dependencies for running the VLM pipeline. |
easyocr |
Installs the EasyOCR OCR engine. |
tesserocr |
Installs the Tesseract binding for using it as OCR engine. |
ocrmac |
Installs the OcrMac OCR engine. |
htmlrender |
Installs dependencies for HTML page rendering in the HTML backend. |
rapidocr |
Installs the RapidOCR OCR engine with onnxruntime backend. |
For Nemotron OCR, install docling-slim[feat-ocr-nemotron] alongside docling as shown below.
OCR engines
Docling supports multiple OCR engines for processing scanned documents. The current version provides the following engines.
| Engine | Installation | Usage |
|---|---|---|
| EasyOCR | easyocr extra or via pip install easyocr. |
EasyOcrOptions |
| Nemotron OCR | docling-slim[feat-ocr-nemotron]. Supported only on Linux x86_64 with Python 3.12 and CUDA 13.x. See installation note below. |
NemotronOcrOptions |
| Tesseract | System dependency. See description for Tesseract and Tesserocr below. | TesseractOcrOptions |
| Tesseract CLI | System dependency. See description below. | TesseractCliOcrOptions |
| OcrMac | System dependency. See description below. | OcrMacOptions |
| RapidOCR | rapidocr extra or via pip install rapidocr onnxruntime |
RapidOcrOptions |
| OnnxTR | Can be installed via the plugin system pip install "docling-ocr-onnxtr[cpu]". Please take a look at docling-OCR-OnnxTR. |
OnnxtrOcrOptions |
The Docling DocumentConverter allows you to choose the OCR engine with the ocr_options settings.
Whichever engine you pick, its languages are given as BCP-47 tags -- see
OCR engines. For example
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
TesseractOcrOptions,
PdfPipelineOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = TesseractOcrOptions() # Use Tesseract
doc_converter = DocumentConverter(
format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
Tesseract installation
Tesseract is a popular OCR engine which is available
on most operating systems. For using this engine with Docling, Tesseract must be installed on your
system, using the packaging tool of your choice. Below we provide example commands.
After installing Tesseract, export TESSDATA_PREFIX with the path to its language files
in the same shell where you start Docling or Python. Run tesseract --list-langs to check
that Tesseract can find the languages you intend to use.
brew install tesseract leptonica pkg-config
export TESSDATA_PREFIX="$(brew --prefix)/share/tessdata/"
tesseract --list-langs
apt-get install tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config
export TESSDATA_PREFIX="$(dpkg -L tesseract-ocr-eng | grep '/tessdata$')"
tesseract --list-langs
dnf install tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel
export TESSDATA_PREFIX=/usr/share/tesseract/tessdata/
tesseract --list-langs
Linking to Tesseract
The most efficient usage of the Tesseract library is via linking. Docling is using the Tesserocr package for this.If you get into installation issues of Tesserocr, we suggest using the following installation options:
pip uninstall tesserocr
pip install --no-binary :all: tesserocr
Nemotron OCR installation
Nemotron OCR requires the CUDA 13 PyTorch wheels.
Install docling together with docling-slim[feat-ocr-nemotron] using uv.
Use uv's unsafe-best-match index strategy to select the CUDA-enabled torch wheels.
uv venv --python 3.12
uv pip install docling "docling-slim[feat-ocr-nemotron]" \
--extra-index-url https://download.pytorch.org/whl/cu130 \
--index-strategy unsafe-best-match
Nemotron OCR is currently supported only on Linux x86_64 with Python 3.12 and CUDA 13.x.
Installation without RapidOCR
The docling package installs docling-slim[standard], which always includes RapidOCR.
If you use another OCR engine, for example the Tesseract CLI, which needs no Python OCR
package, install docling-slim with the extras of standard except feat-ocr-rapidocr:
pip install "docling-slim[format-pdf,models-local,format-office,format-web,format-latex,format-email,format-iwork,feat-chunking,extract-core,service-client,cli]" opencv-python-headless
The table structure model needs OpenCV, which RapidOCR otherwise brings in. Without an OpenCV
package, the conversion of a PDF fails with ModuleNotFoundError: No module named 'cv2'.
Install either opencv-python-headless or opencv-python, not both (see the FAQ).
Add the extra of the OCR engine you use, for example feat-ocr-tesserocr or feat-ocr-easyocr.
The Tesseract CLI only needs the tesseract program, see "Tesseract installation" above.
Then select the OCR engine explicitly. The default automatic selection (OcrAutoOptions) never
selects Tesseract, so without an engine that it can select, it logs
No OCR engine found. Please review the install details. and converts without OCR.
from docling.datamodel.pipeline_options import PdfPipelineOptions, TesseractCliOcrOptions
pipeline_options = PdfPipelineOptions()
pipeline_options.ocr_options = TesseractCliOcrOptions(lang=["eng"])
On the command line, use docling --ocr-engine tesseract --ocr-lang eng.
Set the languages to the Tesseract language data you installed. The default languages of the
Tesseract options are eng, spa, fra and deu, and the conversion fails if one of them
is not installed.
Development setup
To develop Docling features, bugfixes etc., install as follows from your local clone's root dir:
uv sync --all-extras --no-extra feat-ocr-nemotron
The feat-ocr-nemotron extra is intentionally excluded from the default development
setup because it is only usable on Linux x86_64 with Python 3.12 and CUDA 13.x.