mirror of
https://github.com/DS4SD/docling.git
synced 2025-12-08 20:58:11 +00:00
docs: Update installation options with extras and review FAQ (#2548)
* revise install docs Signed-off-by: Michele Dolfi <dol@zurich.ibm.com> * add more FAQ Signed-off-by: Michele Dolfi <dol@zurich.ibm.com> --------- Signed-off-by: Michele Dolfi <dol@zurich.ibm.com>
This commit is contained in:
Michele Dolfi
GitHub
119
docs/installation/index.md
vendored
119
docs/installation/index.md
vendored
@@ -20,37 +20,76 @@ Works on macOS, Linux, and Windows, with support for both x86_64 and arm64 archi
|
||||
pip install docling --extra-index-url https://download.pytorch.org/whl/cpu
|
||||
```
|
||||
|
||||
??? "Alternative OCR engines"
|
||||
??? "Installation on macOS Intel (x86_64)"
|
||||
|
||||
Docling supports multiple OCR engines for processing scanned documents. The current version provides
|
||||
the following engines.
|
||||
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.
|
||||
|
||||
| Engine | Installation | Usage |
|
||||
| ------ | ------------ | ----- |
|
||||
| [EasyOCR](https://github.com/JaidedAI/EasyOCR) | Default in Docling or via `pip install easyocr`. | `EasyOcrOptions` |
|
||||
| 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](https://github.com/RapidAI/RapidOCR) | Extra feature not included in Default Docling installation can be installed via `pip install rapidocr onnxruntime` | `RapidOcrOptions` |
|
||||
| [OnnxTR](https://github.com/felixdittrich92/OnnxTR) | Can be installed via the plugin system `pip install "docling-ocr-onnxtr[cpu]"`. Please take a look at [docling-OCR-OnnxTR](https://github.com/felixdittrich92/docling-OCR-OnnxTR).| `OnnxtrOcrOptions` |
|
||||
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+.
|
||||
|
||||
The Docling `DocumentConverter` allows to choose the OCR engine with the `ocr_options` settings. For example
|
||||
```bash
|
||||
# For uv users
|
||||
uv add torch==2.2.2 torchvision==0.17.2 docling
|
||||
|
||||
```python
|
||||
from docling.datamodel.base_models import ConversionStatus, PipelineOptions
|
||||
from docling.datamodel.pipeline_options import PipelineOptions, EasyOcrOptions, TesseractOcrOptions
|
||||
from docling.document_converter import DocumentConverter
|
||||
# For pip users
|
||||
pip install "docling[mac_intel]"
|
||||
|
||||
pipeline_options = PipelineOptions()
|
||||
pipeline_options.do_ocr = True
|
||||
pipeline_options.ocr_options = TesseractOcrOptions() # Use Tesseract
|
||||
|
||||
doc_converter = DocumentConverter(
|
||||
pipeline_options=pipeline_options,
|
||||
)
|
||||
# For Poetry users
|
||||
poetry add docling
|
||||
```
|
||||
|
||||
<h3>Tesseract installation</h3>
|
||||
## 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 |
|
||||
| - | - |
|
||||
| `asr` | Installs dependencies for running the ASR pipeline. |
|
||||
| `vlm` | Installs dependencies for running the VLM pipeline. |
|
||||
| `easyocr` | Installs the [EasyOCR](https://github.com/JaidedAI/EasyOCR) OCR engine. |
|
||||
| `tesserocr` | Installs the Tesseract binding for using it as OCR engine. |
|
||||
| `ocrmac` | Installs the OcrMac OCR engine. |
|
||||
| `rapidocr` | Installs the [RapidOCR](https://github.com/RapidAI/RapidOCR) OCR engine with [onnxruntime](https://github.com/microsoft/onnxruntime/) backend. |
|
||||
|
||||
|
||||
### OCR engines
|
||||
|
||||
|
||||
Docling supports multiple OCR engines for processing scanned documents. The current version provides
|
||||
the following engines.
|
||||
|
||||
| Engine | Installation | Usage |
|
||||
| ------ | ------------ | ----- |
|
||||
| [EasyOCR](https://github.com/JaidedAI/EasyOCR) | `easyocr` extra or via `pip install easyocr`. | `EasyOcrOptions` |
|
||||
| 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](https://github.com/RapidAI/RapidOCR) | `rapidocr` extra can or via `pip install rapidocr onnxruntime` | `RapidOcrOptions` |
|
||||
| [OnnxTR](https://github.com/felixdittrich92/OnnxTR) | Can be installed via the plugin system `pip install "docling-ocr-onnxtr[cpu]"`. Please take a look at [docling-OCR-OnnxTR](https://github.com/felixdittrich92/docling-OCR-OnnxTR).| `OnnxtrOcrOptions` |
|
||||
|
||||
The Docling `DocumentConverter` allows to choose the OCR engine with the `ocr_options` settings. For example
|
||||
|
||||
```python
|
||||
from docling.datamodel.base_models import ConversionStatus, PipelineOptions
|
||||
from docling.datamodel.pipeline_options import PipelineOptions, EasyOcrOptions, TesseractOcrOptions
|
||||
from docling.document_converter import DocumentConverter
|
||||
|
||||
pipeline_options = PipelineOptions()
|
||||
pipeline_options.do_ocr = True
|
||||
pipeline_options.ocr_options = TesseractOcrOptions() # Use Tesseract
|
||||
|
||||
doc_converter = DocumentConverter(
|
||||
pipeline_options=pipeline_options,
|
||||
)
|
||||
```
|
||||
|
||||
??? "Tesseract installation"
|
||||
|
||||
[Tesseract](https://github.com/tesseract-ocr/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
|
||||
@@ -82,7 +121,7 @@ Works on macOS, Linux, and Windows, with support for both x86_64 and arm64 archi
|
||||
echo "Set TESSDATA_PREFIX=${TESSDATA_PREFIX}"
|
||||
```
|
||||
|
||||
<h3>Linking to Tesseract</h3>
|
||||
<h4>Linking to Tesseract</h4>
|
||||
The most efficient usage of the Tesseract library is via linking. Docling is using
|
||||
the [Tesserocr](https://github.com/sirfz/tesserocr) package for this.
|
||||
|
||||
@@ -94,36 +133,6 @@ Works on macOS, Linux, and Windows, with support for both x86_64 and arm64 archi
|
||||
pip install --no-binary :all: tesserocr
|
||||
```
|
||||
|
||||
<h3>ocrmac installation</h3>
|
||||
|
||||
[ocrmac](https://github.com/straussmaximilian/ocrmac) is using
|
||||
Apple's vision(or livetext) framework as OCR backend.
|
||||
For using this engine with Docling, ocrmac must be installed on your system.
|
||||
This only works on macOS systems with newer macOS versions (10.15+).
|
||||
|
||||
```console
|
||||
pip install ocrmac
|
||||
```
|
||||
|
||||
??? "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+.
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
## Development setup
|
||||
|
||||
To develop Docling features, bugfixes etc., install as follows from your local clone's root dir:
|
||||
|
||||
Reference in New Issue
Block a user