CLI reference
This page documents Docling's command line tools. It is generated by
scripts/render_cli_reference.py from the live Typer apps — do not
edit by hand.
docling
Convert documents to a unified representation, locally with convert or through a docling-serve service with convert-remote.
Usage
docling [OPTIONS] COMMAND [ARGS]...
Subcommands
| Command | Description |
|---|---|
docling convert |
|
docling convert-remote |
Convert via a remote docling-serve service (see docling convert-remote --help). |
docling convert
Usage
docling convert [OPTIONS] source
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
source |
text |
yes | PDF files to convert. Can be local file / directory paths or URL. |
Options
| Name | Type | Default | Description |
|---|---|---|---|
--from |
text (repeatable) |
Input formats to accept. Use 'odf' for odt, ods, and odp. Defaults to all supported formats. | |
--to |
md, json, yaml, html, html_split_page, text, doctags, vtt, doclang, dclx, chunks (repeatable) |
Specify output formats. Defaults to Markdown. | |
--chunks-type |
hybrid, hierarchical |
hybrid |
Chunker type for '--to chunks'. |
--chunks-max-tokens |
integer |
Max tokens per chunk. Defaults to the tokenizer's own limit. | |
--chunks-tokenizer |
text |
sentence-transformers/all-MiniLM-L6-v2 |
HuggingFace tokenizer model name/path. Used only with --chunks-type hybrid. |
--show-layout / --no-show-layout |
flag | false |
If enabled, the page images will show the bounding-boxes of the items. |
--headers |
text |
Specify http request headers used when fetching url input sources in the form of a JSON string | |
--html-image-headers |
text |
Specify http request headers used when fetching HTML and EPUB image resources in the form of a JSON string | |
--image-export-mode |
placeholder, embedded, referenced |
embedded |
Image export mode for image-capable document outputs (JSON, YAML, HTML, HTML split-page, and Markdown). Text, DocTags, and WebVTT outputs do not export images. With placeholder, only the position of the image is marked in the output. In embedded mode, the image is embedded as base64 encoded string. In referenced mode, the image is exported in PNG format and referenced from the main exported document. |
--html-image-fetch |
none, local, remote, all |
none |
Fetch image resources referenced by HTML and EPUB inputs. Choose none, local, remote, or all. |
--pipeline |
legacy, standard, vlm, asr |
standard |
Choose the pipeline to process PDF or image files. |
--vlm-model |
text |
granite_docling |
Choose the VLM preset to use with PDF or image files. Available presets: smoldocling, granite_docling, deepseek_ocr, granite_vision, pixtral, got_ocr, phi4, qwen, nanonets_ocr2, gemma_12b, gemma_27b, dolphin, glm_ocr, lightonocr, falcon_ocr, chandra_ocr2, dots_ocr, dots_mocr |
--asr-model |
whisper_tiny, whisper_small, whisper_medium, whisper_base, whisper_large, whisper_turbo, whisper_tiny_mlx, whisper_small_mlx, whisper_medium_mlx, whisper_base_mlx, whisper_large_mlx, whisper_turbo_mlx, whisper_tiny_native, whisper_small_native, whisper_medium_native, whisper_base_native, whisper_large_native, whisper_turbo_native, whisper_tiny_en_native, whisper_base_en_native, whisper_small_en_native, whisper_medium_en_native, whisper_distil_small_en_native, whisper_distil_medium_en_native, whisper_distil_large_v3_native, whisper_distil_large_v3_5_native, whisper_tiny_s2t, whisper_tiny_en_s2t, whisper_base_s2t, whisper_base_en_s2t, whisper_small_s2t, whisper_small_en_s2t, whisper_distil_small_en_s2t, whisper_medium_s2t, whisper_medium_en_s2t, whisper_distil_medium_en_s2t, whisper_large_v3_s2t, whisper_distil_large_v3_s2t, whisper_distil_large_v3_5_s2t, whisper_large_v3_turbo_s2t |
whisper_tiny |
Choose the ASR model to use with audio/video files. |
--ocr / --no-ocr |
flag | true |
If enabled, the bitmap content will be processed using OCR. |
--force-ocr / --no-force-ocr |
flag | false |
Replace any existing text with OCR generated text over the full content. |
--tables / --no-tables |
flag | true |
If enabled, the table structure model will be used to extract table information. |
--ocr-engine |
text |
auto |
The OCR engine to use. When --allow-external-plugins is not set, the available values are: auto, easyocr, kserve_v2_ocr, nemotron-ocr, ocrmac, rapidocr, tesserocr, tesseract. Use the option --show-external-plugins to see the options allowed with external plugins. |
--ocr-lang |
text |
Provide a comma-separated list of languages used by the OCR engine. Note that each OCR engine has different values for the language names. | |
--psm |
integer |
Page Segmentation Mode for the OCR engine (0-13). | |
--pdf-backend |
pypdfium2, docling_parse, threaded_docling_parse, dlparse_v1, dlparse_v2, dlparse_v4 |
docling_parse |
The PDF backend to use. |
--pdf-password |
text |
Password for protected PDF documents | |
--table-mode |
fast, accurate |
accurate |
The mode to use in the table structure model. |
--enrich-code / --no-enrich-code |
flag | false |
Enable the code enrichment model in the pipeline. |
--enrich-formula / --no-enrich-formula |
flag | false |
Enable the formula enrichment model in the pipeline. |
--enrich-picture-classes / --no-enrich-picture-classes |
flag | false |
Enable the picture classification enrichment model in the pipeline. |
--enrich-picture-description / --no-enrich-picture-description |
flag | false |
Enable the picture description model in the pipeline. |
--enrich-chart-extraction / --no-enrich-chart-extraction |
flag | false |
Enable chart data extraction from bar, pie, and line charts. |
--artifacts-path |
path |
If provided, the location of the model artifacts. | |
--enable-remote-services / --no-enable-remote-services |
flag | false |
Must be enabled when using models connecting to remote services. |
--allow-external-plugins / --no-allow-external-plugins |
flag | false |
Must be enabled for loading modules from third-party plugins. |
--show-external-plugins / --no-show-external-plugins |
flag | false |
List the third-party plugins which are available when the option --allow-external-plugins is set. |
--abort-on-error / --no-abort-on-error |
flag | false |
If enabled, the processing will be aborted when the first error is encountered. |
--output |
path |
. |
Output directory where results are saved. |
--verbose / -v |
integer |
0 |
Set the verbosity level. -v for info logging, -vv for debug logging. |
--debug-visualize-cells / --no-debug-visualize-cells |
flag | false |
Enable debug output which visualizes the PDF cells |
--debug-visualize-ocr / --no-debug-visualize-ocr |
flag | false |
Enable debug output which visualizes the OCR cells |
--debug-visualize-layout / --no-debug-visualize-layout |
flag | false |
Enable debug output which visualizes the layout clusters |
--debug-visualize-tables / --no-debug-visualize-tables |
flag | false |
Enable debug output which visualizes the table cells |
--version |
flag | Show version information. | |
--document-timeout |
float |
The timeout for processing each document, in seconds. | |
--num-threads |
integer |
4 |
Number of threads |
--release-native-memory-every-n-pages |
integer |
128 |
Release native parser memory after every N decoded pages when using the threaded docling-parse backend. |
--device |
auto, cpu, cuda, mps, xpu |
auto |
Accelerator device |
--logo |
flag | Docling logo | |
--page-batch-size |
integer |
4 |
Number of pages processed in one batch. Default: 4 |
--profiling / --no-profiling |
flag | false |
If enabled, it summarizes profiling details for all conversion stages. |
--save-profiling / --no-save-profiling |
flag | false |
If enabled, it saves the profiling summaries to json. |
docling convert-remote
Convert documents through a remote docling-serve service instead of locally.
Sources may be local files, local directories (walked and filtered by --from),
or http(s) URLs. Results are written to --output in the formats given by --to,
identical to docling convert. Only options the service honors are exposed here;
local-execution flags (device, threads, pdf-backend internals, debug visualizers)
do not apply to remote conversion and are intentionally absent.
Usage
docling convert-remote [OPTIONS] source
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
source |
text |
yes | Documents to convert: local file/directory paths or http(s) URLs. |
Options
| Name | Type | Default | Description |
|---|---|---|---|
--service-url |
text |
Base URL of the docling-serve service (required; falls back to DOCLING_SERVICE_URL or a .env file). | |
--api-key |
text |
API key for the service (optional; falls back to DOCLING_SERVICE_API_KEY or a .env file; omit if unauthenticated). | |
--from |
docx, pptx, html, image, pdf, asciidoc, md, csv, xlsx, odt, ods, odp, xml_uspto, xml_jats, xml_xbrl, xml_doclang, dclx, mets_gbs, json_docling, audio, vtt, latex, email, epub, boxnote (repeatable) |
Input formats to accept; filters directories and is sent as the server allow-list. Defaults to all supported formats. | |
--to |
md, json, yaml, html, html_split_page, text, doctags, vtt, doclang, dclx, chunks (repeatable) |
Output formats to produce and write locally. Defaults to Markdown. | |
--chunks-type |
hybrid, hierarchical |
hybrid |
Chunker type for '--to chunks'. |
--chunks-max-tokens |
integer |
Max tokens per chunk. Defaults to the tokenizer's own limit. | |
--chunks-tokenizer |
text |
sentence-transformers/all-MiniLM-L6-v2 |
HuggingFace tokenizer model name/path. Used only with --chunks-type hybrid. |
--ocr / --no-ocr |
flag | true |
If enabled, the service processes bitmap content using OCR. |
--force-ocr / --no-force-ocr |
flag | false |
Replace any existing text with OCR-generated text over the full content. |
--tables / --no-tables |
flag | true |
If enabled, the service extracts table structure. |
--pipeline |
legacy, standard, vlm, asr |
standard |
Pipeline the service uses to process PDF or image files. |
--ocr-lang |
text |
Comma-separated list of OCR languages (engine-specific names). | |
--enrich-code / --no-enrich-code |
flag | false |
Enable the service's code enrichment model. |
--enrich-formula / --no-enrich-formula |
flag | false |
Enable the service's formula enrichment model. |
--enrich-picture-classes / --no-enrich-picture-classes |
flag | false |
Enable the service's picture classification model. |
--enrich-picture-description / --no-enrich-picture-description |
flag | false |
Enable the service's picture description model. |
--enrich-chart-extraction / --no-enrich-chart-extraction |
flag | false |
Enable the service's chart data extraction. |
--image-export-mode |
placeholder, embedded, referenced |
Image export mode for image-capable outputs (JSON, YAML, HTML, Markdown): embedded, placeholder, or referenced. If unset, the service default applies. | |
--page-range |
text |
Only convert a range of pages, e.g. 1-4 (page numbers start at 1). | |
--document-timeout |
float |
Server-side timeout for processing each document, in seconds. | |
--abort-on-error / --no-abort-on-error |
flag | false |
If enabled, the service aborts the batch on the first error. |
--max-concurrency |
integer |
8 |
Maximum number of documents converted concurrently against the service. |
--timeout |
float |
300.0 |
Client-side timeout waiting for each job to finish, in seconds. |
--watcher |
websocket, polling |
websocket |
How the client tracks job status: websocket (default) or polling. |
--output |
path |
. |
Output directory where results are saved. |
--verbose / -v |
integer |
0 |
Set the verbosity level. -v for info logging, -vv for debug logging. |
docling-tools
Usage
docling-tools [OPTIONS] COMMAND [ARGS]...
Subcommands
| Command | Description |
|---|---|
docling-tools models |
docling-tools models
Usage
docling-tools models [OPTIONS] COMMAND [ARGS]...
Subcommands
| Command | Description |
|---|---|
docling-tools models download |
|
docling-tools models download-hf-repo |
docling-tools models download
Usage
docling-tools models download [OPTIONS] [MODELS]:[layout|tableformer|tableformerv2|code_formula|picture_classifier|smolvlm|granitedocling|granitedocling_mlx|smoldocling|smoldocling_mlx|granite_vision|granite_chart_extraction|granite_chart_extraction_v4|rapidocr|easyocr|nemotron_ocr_v2]...
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
MODELS |
layout, tableformer, tableformerv2, code_formula, picture_classifier, smolvlm, granitedocling, granitedocling_mlx, smoldocling, smoldocling_mlx, granite_vision, granite_chart_extraction, granite_chart_extraction_v4, rapidocr, easyocr, nemotron_ocr_v2 |
no | Models to download (default behavior: a predefined set of models will be downloaded). |
Options
| Name | Type | Default | Description |
|---|---|---|---|
-o / --output-dir |
path |
/home/runner/.cache/docling/models |
The directory where to download the models. |
--force / --no-force |
flag | false |
If true, the download will be forced. |
--all |
flag | false |
If true, all available models will be downloaded (mutually exclusive with passing specific models). |
-q / --quiet |
flag | false |
No extra output is generated, the CLI prints only the directory with the cached models. |
docling-tools models download-hf-repo
Usage
docling-tools models download-hf-repo [OPTIONS] MODELS...
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
MODELS |
text |
yes | Specific models to download from HuggingFace identified by their repo id. For example: docling-project/docling-models . |
Options
| Name | Type | Default | Description |
|---|---|---|---|
-o / --output-dir |
path |
/home/runner/.cache/docling/models |
The directory where to download the models. |
--force / --no-force |
flag | false |
If true, the download will be forced. |
-q / --quiet |
flag | false |
No extra output is generated, the CLI prints only the directory with the cached models. |