Docling Model Management#

Docling's document-conversion pipeline relies on several ML models for PDF processing: layout detection, table structure recognition, OCR, picture classification, code/formula extraction, and optional VLMs. These models come from two sources:

• HuggingFace — layout model, TableFormer, picture classifier, code/formula model, and all VLMs (Granite Vision, GraniteDocling, SmolVLM, SmolDocling, etc.)
• ModelScope — RapidOCR artifacts only (https://www.modelscope.cn)

By default, models download automatically on first use. For offline or air-gapped environments, use the docling-tools models download CLI to pre-download them, then point the runtime to the local directory via artifacts_path.

The two primary mechanisms are:

1. docling-tools models download — CLI that pre-fetches a named set of models into a local directory
2. artifacts_path on PipelineOptions — tells the runtime where to look for pre-downloaded artifacts instead of fetching from the network

CLI: docling-tools models download#

Defined in docling/cli/models.py, the download subcommand fetches one or more models into a local directory.

Basic usage:

# Download default model set (layout, tableformer, code_formula, picture_classifier, rapidocr)
docling-tools models download -o /path/to/models

# Download all available models
docling-tools models download --all -o /path/to/models

# Download specific models
docling-tools models download granitedocling granite_vision -o /path/to/models

# Force re-download (overwrite existing)
docling-tools models download --force -o /path/to/models

# Quiet mode — prints only the output path (useful for scripting)
docling-tools models download -q -o /path/to/models

Available model names 1:

Default set (downloaded when no model names are specified) 2: layout, tableformer, code_formula, picture_classifier, rapidocr.

After download, the CLI prints the path and a reminder of the --artifacts-path flag to use:

Docling can now be configured for running offline using the local artifacts.
Using the CLI: `docling --artifacts-path=/path/to/models FILE`

Secondary subcommand — download-hf-repo: downloads any arbitrary HuggingFace repo by ID, useful for custom or private models 3:

docling-tools models download-hf-repo my-org/my-custom-model -o /path/to/models

Offline Deployment via artifacts_path#

artifacts_path is a field on the base PipelineOptions class (inherited by PdfPipelineOptions, VlmPipelineOptions, etc.). Setting it tells each model stage to load from that directory instead of downloading from the network. 4

Python:

from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat

pipeline_options = PdfPipelineOptions(artifacts_path="/path/to/models")
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

CLI:

docling --artifacts-path=/path/to/models convert document.pdf

docling-serve#

In docling-serve, models are baked into the container image at build time via docling-tools models download 5, then served via the DOCLING_SERVE_ARTIFACTS_PATH environment variable (default: /opt/app-root/src/.cache/docling/models). For custom deployments, mount a pre-downloaded model directory and set this environment variable to its path.

PipelineOptions hierarchy#

artifacts_path sits at the top-level PipelineOptions and is available across all pipeline types 6:

PipelineOptions ← artifacts_path lives here
└── ConvertPipelineOptions
    └── PaginatedPipelineOptions
        ├── PdfPipelineOptions
        └── VlmPipelineOptions

HuggingFace Models and Environment Variables#

Most Docling models are fetched from HuggingFace Hub using huggingface_hub. The primary HF repository for non-VLM models is ds4sd/docling-models. VLM checkpoints are fetched from their respective ibm-granite/ or docling-project/ org repos.

Relevant environment variables:

The internal download utility download_hf_model wraps huggingface_hub.snapshot_download / hf_hub_download and is used for all VLM-family models. Files that already exist on disk are skipped unless --force is passed.

VLM-specific model identifiers#

The key Granite and SmolDocling HuggingFace repo IDs 8:

VLM models are not included in the default docling-tools models download set — they must be explicitly named 2.

SSL and Certificate Issues#

Model downloads can fail with SSL: CERTIFICATE_VERIFY_FAILED when Python's certificate store is outdated. This affects both HuggingFace downloads and RapidOCR downloads from ModelScope. 9

Solutions in order of preference:

1. Upgrade certifi: pip install --upgrade certifi
2. Use system certificates: pip install pip-system-certs
3. Manually point to the certificate bundle:
   ⧉

   CERT_PATH=$(python -m certifi)
   export SSL_CERT_FILE=${CERT_PATH}
   export REQUESTS_CA_BUNDLE=${CERT_PATH}
   

For corporate proxies or custom CA environments (e.g., air-gapped container builds), REQUESTS_CA_BUNDLE must point to the corporate root CA certificate 10.

Key Files and Entry Points#