Dosu LogoDosu Logo
Ask
Join our Discord
DoclingPublic
IBM Docling
DocumentsDocling
Docling Model Management
Docling Model Management
Type
Topic
Status
Published
Created
Jul 15, 2026
Updated
Jul 15, 2026

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 :

NameDescription
layoutLayout detection model (default)
tableformerTableFormer V1 table structure (default)
tableformerv2TableFormer V2
code_formulaCode/formula extraction (default)
picture_classifierPicture type classifier (default)
rapidocrRapidOCR models for Chinese + English (default)
granitedoclingIBM Granite-Docling-258M (HuggingFace Transformers)
granitedocling_mlxGranite-Docling-258M MLX variant (Apple Silicon)
smolvlmSmolVLM picture description
smoldoclingSmolDocling-256M VLM pipeline
smoldocling_mlxSmolDocling MLX variant
granite_visionGranite Vision 3.3-2B (picture description)
granite_chart_extractionGranite Vision chart extraction V3
granite_chart_extraction_v4Granite Vision 4.1-4B chart extraction V4
easyocrEasyOCR models
nemotron_ocr_v2NVIDIA NemotronOCR V2

Default set (downloaded when no model names are specified) : 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 :

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.

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 , 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 :

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:

VariableEffect
HF_HOMEOverride HuggingFace cache root directory
HF_HUB_DOWNLOAD_TIMEOUTTimeout for individual file downloads
HF_HUB_ETAG_TIMEOUTTimeout for etag/freshness checks
HF_TOKENAuth token for private repos (not yet exposed via Docling CLI — see open feature request)
DOCLING_CUDA_USE_FLASH_ATTENTION2Set to 1 to enable Flash Attention 2 on CUDA

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 :

ModelHuggingFace Repo
GraniteDocling-258Mibm-granite/granite-docling-258M
GraniteDocling-258M (MLX)ibm-granite/granite-docling-258M-mlx
Granite Vision 3.3-2Bibm-granite/granite-vision-3.3-2b
Granite Vision 4.1-4Bibm-granite/granite-vision-4.1-4b
Granite Vision chart V3ibm-granite/granite-vision-3.3-2b-chart2csv-preview
SmolVLMHuggingFaceTB/SmolVLM-256M-Instruct
SmolDoclingds4sd/SmolDocling-256M-Preview
CodeFormulaV2docling-project/CodeFormulaV2

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

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.

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 .

Key Files and Entry Points#

FilePurpose
docling/cli/models.pydocling-tools models download CLI — model name enum, default set, download and download-hf-repo commands
docling/utils/model_downloader.pydownload_models() — orchestrates downloads for all model types
docling/models/utils/hf_model_download.pydownload_hf_model() — wraps huggingface_hub for VLM checkpoints
docling/datamodel/pipeline_options.pyPipelineOptions.artifacts_path — the top-level field for offline path override
docs/faq/index.mdFAQ: offline deployment, required model weights, SSL errors
Documents
Agentic Document Processing
API Authentication
Apple Silicon Support
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
Bibliography Extraction and Parsing
Bounding Box Visualization
Caption-Figure Linking
Chart Extraction
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Chemical Notation OCR
Citation Data Modeling
CLI File Staging and Collision Handling
CLI Image Export Modes
How can I improve the resolution or quality of images extracted from a PDF using docling?
Code Chunking
Container Image Variants
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Cross-Platform Support
Custom Enrichment Models
Custom Layout Plugin Architecture
DocItemLabel Type System
DocLang Format
Docling Image Extraction
How can I improve the resolution or quality of images extracted from a PDF using docling?
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Docling Model Management
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Docling Pipeline Configuration
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Docling Resource Requirements
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Docling Rust SDK
Docling Serve API Client
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
Docling Serve Configuration
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
How can you mount a PersistentVolumeClaim (PVC) in docling-serve on OpenShift to store EasyOCR models, and what steps are required to ensure docling-serve can access these models?
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Docling Serve Deployment
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
How can you mount a PersistentVolumeClaim (PVC) in docling-serve on OpenShift to store EasyOCR models, and what steps are required to ensure docling-serve can access these models?
Models handling in Docling Serve
skill.md
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Docling Serve Worker Architecture
DoclingDocument Builder API
Building a Modular IDP Pipeline with Docling Components
DoclingDocument Data Model
Building a Modular IDP Pipeline with Docling Components
DoclingDocument Hierarchization
DoclingDocument Java Serialization
DoclingDocument Serialization
Document Backends
Building a Modular IDP Pipeline with Docling Components
Document Chunk Metadata and Provenance
Document Chunking
Document Content Classification
Document Extraction Strategies
Document Figure Classification
Document Input Methods
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
Document Layout and Reading Order
How does Docling reconstruct reading order without using a large language model (LLM) call in an unsupervised manner?
Document Layout Detection Models
Building a Modular IDP Pipeline with Docling Components
Document Merging and Concatenation
Document Metadata
Document Pagination
Document Rotation and Orientation
Document Serialization Architecture
Document Tree Traversal
Document Type Classification and Routing
Document-to-Graph Pipeline
DocumentConverter Configuration
How can I use granite-docling to process all PDFs in a directory and output doctags?
DOCX Header/Footer Processing
DOCX Image Extraction
DOCX List Processing
DOCX Numbered Heading Processing
DOCX Reference and Citation Extraction
DOCX SDT Handling
DOCX Table Extraction
DOCX Text Formatting
Email Format Support
Enrichment Pipeline
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Excel Backend Processing
Models handling in Docling Serve
Extraction Pipeline Prompting
GPU Accelerator Support
GPU Memory Management
Heading Hierarchy Configuration
HTML Export Format
HuggingFace Transformers Integration
IBM Watsonx and Granite Integration
How can I use granite-docling to process all PDFs in a directory and output doctags?
Image Reference Handling
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
skill.md
Input Format and Image Support
Knowledge Graph Extraction
Large PDF Memory Management
Layout Detection Configuration
Layout Postprocessor
Layout Prediction Data Structures
Building a Modular IDP Pipeline with Docling Components
LibreOffice Integration
List Marker Normalization
Markdown Export Configuration
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
Markdown Processing
MCP Server Integration
Docling MCP in Docling Serve
Multi-Language API Integration
Native Library Compatibility
NuExtract Transformers Compatibility
OCR Engine Configuration
OCR Engine Integration
OCR Language Support
ODF Backend Processing
Open WebUI Integration
Optional Dependency Management
Package Architecture
skill.md
Page Assembly Pipeline
Parsed Page Access and Segmentation
PDF Document Pipeline
Building a Modular IDP Pipeline with Docling Components
PDF Page Range Selection
PDF Parse Lifecycle Management
PDF Pipeline Configuration
How can I improve the resolution or quality of images extracted from a PDF using docling?
PDF Rendering and OCR Pipeline
How can I improve the resolution or quality of images extracted from a PDF using docling?
PDF Spatial Filtering
PDF Text Extraction
PDF-to-RAG Pipeline
skill.md
Picture Classification Filtering
Picture Detection and Segmentation
Pipeline and Model Caching
skill.md
Pipeline Batch Size Configuration
Pipeline Error Logging
Pipeline Initialization and Dependency Loading
Pipeline Stage Architecture
PPTX Content Extraction
Pydantic-Based Extraction Templates
RAG Framework Connectors
RapidOCR Model Management
Redis Integration
Remote Inference Services
Resource Cleanup and Lifecycle Management
RTL and Bidirectional Text Support
Security Hardening
Spatial Predicates and R-tree Indexing
Structured Information Extraction
How can I use granite-docling to process all PDFs in a directory and output doctags?
skill.md
Table Cell Formatting
Table Cell Text Matching
Table Chunking
Table Export and Serialization
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Table Structure Recognition
Building a Modular IDP Pipeline with Docling Components
Models handling in Docling Serve
TableFormer Confidence Scoring
Text Element Merging and Dehyphenation
Threaded PDF Backend
Tokenizer Backends
Torch Compile Optimization
VLM Extraction Pipeline
VLM Formula and Code Extraction
VLM Image Cropping
VLM Inference Configuration
VLM Inference Engine
Building a Modular IDP Pipeline with Docling Components
VLM Picture Description
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
VLM Pipeline
VLM Token Limits and Truncation
XML Backend Architecture
Can I use a custom OCR model in Docling, and how do I set its path in the pipeline options?
Can docling-serve fetch documents from object storage (e.g., S3)?
Comment corriger la phrase : "Je suis allé à l'école en pied et mains je parte par quotidien des beaucoup de kilomètres cela est importante" ?
Content Layers
Does Docling automatically detect the language of a document when sending images to Tesseract OCR, and how can it be configured?
How can I enable and use GPU acceleration with Docling?
How can I find page numbers and bounding box information for content in a chunk produced by the hybrid chunker, and what is the structure of the doc_items list within a chunk?
How can a student build a local, open-source LLM-based system to extract and analyze technical PDF documents (PMS/IDC) and generate instrumentation datasheets, using Python on a PC with limited resources?
How can a student build a local, open-source, privacy-preserving AI system to extract and query technical PDF documents (PMS/IDC) on a PC with limited resources?
How can you make Docling read/understand images embedded in a DOCX file, and what is the correct code to use the VlmPipeline for this purpose?
How can you use Docling's REST API to convert a PDF to Markdown and generate image descriptions using an OpenAI model?
How do I set up a complete multi-format document processing pipeline using Docling that handles technical PDFs, HTML files, images, videos, audio, codebases, and schematics, and exports everything to organized agent-friendly markdown files?
How do you install and use Docling in Python on WSL2, including integration with an AI agent?
How do you use HybridChunker in Docling, including saving and reloading the converted document?
How does Docling support parallel/multiprocessing for document conversion, and what do the key performance parameters (`page_chunk_size`, `doc_batch_concurrency`, `doc_batch_size`) do?
How to properly enable `enable_remote_services` in Docling Serve (CPU image) to use an external OpenAI-compatible API for picture description and formula enrichment, and what is the correct config format?
No Docling, o uso de CUDA é obrigatório para processar PDFs com extração de texto e descrição de imagens, ou é opcional?
Quais são as melhores opções de OCR para extração de tabelas financeiras complexas em PDFs usando Docling, incluindo alternativas externas e integração com plugins?
Quelle est l'origine et le statut des êtres mathématiques selon Platon et John Stuart Mill ?
What are all the parameters of HybridChunker in Docling, and how do you use it with a custom tokenizer?
What are all the pipelines that exist in Docling, including their purposes, selection criteria, and how they handle scanned documents?
What are the detailed pipeline options and processing behaviors for PDF, DOCX, PPTX, and XLSX files in the Python SDK?
What are the steps to convert a complex payment advice PDF to Excel using Docling?
What does 'RFLP' stand for or refer to?
What is the best practice for extracting text from a mixed PDF (digital + scanned pages) for enterprise financial document processing without a GPU and with limited costs?
What is the best practice for processing a mixed PDF (digital + scanned pages) containing sensitive financial data in Docling, given no GPU and limited cost?
What is the general sentiment expressed about the messy nature of documents and content in the Docling project?
What is the recommended architecture and implementation for processing a mixed PDF bundle (digital + scanned pages) for an enterprise financial payment verification system (like MRT Jakarta's AI-Augmented Payment Flow), with constraints of no GPU and limited cost?
When processing large PDFs (700+ pages) with Docling's StandardPdfPipeline, what causes the `std::bad_alloc` errors and what are the recommended workarounds?
Which is the better option for running Docling: using 'docling serve' in Azure Container Apps or code-based deployment in Azure Function App (Windows Premium plan)?
Why are bounding boxes not available for items (such as images, tables, text) when using VlmPipeline with certain VLM presets (like Qwen/Markdown)?
Zoom on Layer 1 (L1): Layout Detection & Routing in a Modular IDP Pipeline
คู่มือการดึงรูปภาพจาก PDF และสร้าง Markdown พร้อม Alternative Text ด้วย Docling