Independent guide — not affiliated with IBM or the Docling project. Every command verified on Docling 2.148.0.
docling.orgIndependent Docling guide
  1. Home
  2. CLI reference
CLI reference

Docling CLI reference — every option, straight from the tool

We generated this reference by reading the CLI's own parameter definitions from Docling 2.148.0 — so names, defaults and choices are exactly what your terminal accepts. Search it, then copy a tested recipe.

Verified on Docling 2.148.0Updated 6 Nov 202610 min read
In short
  • Syntax: docling convert [OPTIONS] SOURCE. SOURCE can be a file, a folder or a URL; convert is the default command, so docling SOURCE also works.
  • Pick outputs with repeatable --to (md, json, yaml, html, html_split_page, text, doctags, vtt, doclang, dclx, chunks, latex). Default: Markdown into the current folder.
  • Engine-specific settings go through --ocr-option, --layout-option and --table-structure-option as KEY=VALUE; docling options ocr rapidocr lists the keys.
  • New since 2.144.0: --replace-broken-text-layer (OCR only pages whose PDF text is garbage) and --heading-hierarchy (real heading levels for PDFs).
  • --force-ocr and --psm are deprecated in 2.148.0: use --ocr-mode full_page and --ocr-option psm=N.

Search every option#

Type a word (/ focuses the box) or filter by group. Defaults shown are the CLI's own; values in code are the accepted choices.

Syntax#

bash
docling convert [OPTIONS] SOURCE
docling SOURCE [OPTIONS]                # same thing: convert is the default command
docling options {ocr|layout|table-structure} [ENGINE]
docling --version

SOURCE may be a file path, a folder (walked recursively and filtered by --from) or an http(s) URL. Output files are named after the input and written to --output (default: the current folder).

Tested recipes#

Each of these ran on Docling 2.148.0. Swap the file names for yours.

Formats and output

bashPDF to Markdown and JSON
docling convert report.pdf --to md --to json --output out/
basha whole folder, PDFs only, keep going on errors
docling convert ./inbox --from pdf --to md --output ./out
bashexact output file (one input, one format)
docling convert report.pdf --to md --output-file report.md
bashfirst 10 pages only
docling convert report.pdf --page-range 1-10
bashimages as separate PNG files in a report_artifacts folder, linked from the Markdown
docling convert report.pdf --to md --image-export-mode referenced --output out/
bashside-by-side HTML with the detected layout drawn on each page
docling convert report.pdf --to html_split_page --show-layout

OCR

bashborn-digital PDF: skip OCR (fastest)
docling convert report.pdf --no-ocr
bashscan with a bad text layer: OCR every page
docling convert scan.pdf --ocr-mode full_page
bashPDF text copies out as garbage: OCR only the broken pages
docling convert contract.pdf --replace-broken-text-layer
bashTesseract with German and English
docling convert scan.pdf --ocr-engine tesseract --ocr-lang deu,eng
bashRapidOCR, Japanese, PyTorch backend (works with the default install)
docling convert scan.pdf --ocr-engine rapidocr --ocr-option backend=torch --ocr-lang iso:ja

Tables, enrichment and models

bashfaster table model
docling convert report.pdf --table-mode fast
bashheading levels (#, ##, ###) from bookmarks, numbering and font size
docling convert report.pdf --heading-hierarchy
bashformulas to LaTeX and code blocks
docling convert paper.pdf --enrich-formula --enrich-code
bashvision-language pipeline with Granite-Docling (GPU recommended)
docling convert report.pdf --pipeline vlm --vlm-model granite_docling
bashaudio transcript (needs docling[asr] and FFmpeg)
docling convert meeting.mp3 --pipeline asr --asr-model whisper_turbo --to md --to vtt

RAG and automation

bashtoken-limited chunks for a vector store
docling convert report.pdf --to chunks --chunks-max-tokens 512 --output chunks/
bashquiet, fail on partial results — for scripts and CI
docling convert ./inbox --to json --quiet --fail-on partial --output ./out
bashfind out where the time goes
docling convert report.pdf --profiling

The options command#

Engines have more settings than dedicated flags. docling options lists the engines of a pipeline stage and the keys each accepts; pass those keys with the matching --*-option KEY=VALUE flag. Values are parsed as JSON when possible (0.6, false, ["en","de"]).

bash
docling options ocr                # auto easyocr kserve_v2_ocr nemotron-ocr ocrmac rapidocr tesserocr tesseract
docling options layout             # layout_object_detection docling_layout_default docling_experimental_table_crops_layout
docling options table-structure    # docling_tableformer docling_tableformer_v2 granite_vision_table
docling options ocr rapidocr       # keys: mode, lang, scale, backend, model_size, text_score, …
bashexample
docling convert scan.pdf --ocr-engine rapidocr --ocr-option backend=torch --ocr-option model_size=tiny --ocr-option text_score=0.6

Exit codes#

--fail-onExit code 1 when…
failure (default)any document fails
partialany document fails or is only partially converted
nevernever — always exits 0

By default a folder conversion continues after a failed file; add --abort-on-error to stop at the first one.

Deprecated and renamed flags#

If a command from an older tutorial misbehaves, check this table first.

OldUse in 2.148.0Why
--force-ocr--ocr-mode full_pageMarked DEPRECATED in the CLI help
--psm N--ocr-option psm=NMarked DEPRECATED; engine settings moved to --ocr-option
--ocr-lang chinese / english (RapidOCR)--ocr-lang ch / en, or iso:zh-HansOld spellings still resolve, with a warning

Remote conversion#

With the service-client extra installed, the CLI gains docling convert-remote, which sends documents to a docling-serve server and writes the results locally. It needs no PyTorch — the environment was 258 MB in our test.

bash
pip install "docling-slim[service-client]"
export DOCLING_SERVICE_URL=http://localhost:5001
export DOCLING_SERVICE_API_KEY=...        # only if the server requires one
docling convert-remote report.pdf --to md --output out/

Environment variables#

VariableEffect
DOCLING_ARTIFACTS_PATHFolder with pre-downloaded models (same as --artifacts-path)
DOCLING_SERVICE_URL, DOCLING_SERVICE_API_KEYServer and key for convert-remote
OMP_NUM_THREADSCaps threads used by the underlying math libraries

Frequently asked questions

What is the basic Docling command?

docling convert file.pdf converts a PDF to Markdown in the current folder. Add --to json, --to html or other --to values for more formats, and --output DIR to choose where files go.

How do I disable OCR in the Docling CLI?

Add --no-ocr. It is the right choice for PDFs that already contain text and was 3.6 times faster in our benchmark.

How do I convert a whole folder with Docling?

Pass the folder as SOURCE: docling convert ./inbox --to md --output ./out. Add --from pdf to only pick up PDFs and --abort-on-error to stop at the first failure.

How do I see the options for one OCR engine?

Run docling options ocr ENGINE, for example docling options ocr rapidocr. It prints every KEY you can pass with --ocr-option KEY=VALUE, with type and default.

What does docling convert return as exit code?

By default it exits with 1 if any document fails. --fail-on partial also fails on partially converted documents, and --fail-on never always exits 0.

Sources

Keep going

Config builder

Build a CLI command, Python script or API call

Python API

DocumentConverter, pipeline options, DoclingDocument

OCR

7 engines, languages, modes and when to turn OCR off

Performance

Measured stage timings and what makes Docling fast

Troubleshooting

Real error messages and the fix for each

Recipes

Copy-paste scripts we ran on 2.148.0