CLI Image Export Modes#
Overview#
The Docling CLI convert command controls how images appear in exported documents via the --image-export-mode flag. The flag accepts one of three ImageRefMode values and applies uniformly to all image-capable output formats.
The Three Modes#
ImageRefMode is defined in docling_core/types/doc/base.py with three values:
| Mode | CLI value | Behavior |
|---|---|---|
PLACEHOLDER | placeholder | Emits a static marker (e.g. <!-- image -->) in place of the image |
EMBEDDED | embedded | Serializes the image as a base64-encoded string inline in the output |
REFERENCED | referenced | Writes the image to a separate PNG file and inserts a file-path reference |
Default: embedded
Which formats honor --image-export-mode#
The flag applies to JSON, YAML, HTML, HTML split-page, and Markdown outputs. The following output formats do not export images regardless of the mode: text, doctags, vtt, doclang, and chunks.
Note: Plain-text (
.txt) export hard-codesImageRefMode.PLACEHOLDERand ignores--image-export-mode.
Pipeline Image Generation#
The export mode alone does not cause images to be generated during conversion. That is controlled separately by two pipeline flags: generate_page_images and generate_picture_images, both defined on PaginatedPipelineOptions and PdfPipelineOptions with a default of False.
The CLI wires these together automatically: when the selected mode is not PLACEHOLDER and at least one image-capable output format is requested, _should_generate_export_images() returns True and the CLI sets both flags to True and forces images_scale = 2.
_should_generate_export_images(image_export_mode, to_formats)
→ True → pipeline_options.generate_page_images = True
pipeline_options.generate_picture_images = True # FIXME: to be deprecated in v3
pipeline_options.images_scale = 2
The # FIXME comment in the source flags generate_picture_images for deprecation in version 3.
Deprecated Pipeline Field#
generate_table_images on PdfPipelineOptions is already formally deprecated. Its Field annotation carries the deprecation message: "Use generate_page_images=True and call TableItem.get_image() to extract table images from page images."
Key Source Files#
| File | Purpose |
|---|---|
docling/cli/main.py | Declares --image-export-mode, default embedded, passes mode to export_documents() |
docling/cli/export_utils.py | _should_generate_export_images() — decides whether the pipeline must generate images |
docling/datamodel/pipeline_options.py | PdfPipelineOptions: generate_page_images, generate_picture_images, generate_table_images (deprecated) |
docling_core/types/doc/base.py | ImageRefMode enum definition |