Docling Image Extraction#

Extracting images from documents in Docling involves two coordinated steps: enabling image generation in PdfPipelineOptions so that pixel data is retained during conversion, and then accessing that data through PictureItem (or page objects) in the resulting DoclingDocument.

1. Pipeline Configuration#

Three fields on PdfPipelineOptions (and its parent PaginatedPipelineOptions) control image generation 1:

Both flags default to False; no pixel data is kept unless at least one is set. generate_page_images = True is sufficient for PictureItem.get_image(doc) because the method falls back to cropping the page image when self.image is None 2.

Minimal setup to enable image extraction:

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

pipeline_options = PdfPipelineOptions()
pipeline_options.images_scale = 2.0
pipeline_options.generate_page_images = True
pipeline_options.generate_picture_images = True # optional: stores image per PictureItem

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
result = converter.convert("document.pdf")

See export_figures.py for the canonical example.

Note: generate_picture_images is flagged for deprecation in v3; prefer generate_page_images + get_image() going forward. 1

2. Accessing Images via PictureItem#

PictureItem extends FloatingItem which inherits from DocItem. The key access patterns are:

PictureItem.get_image(doc, prov_index=0) → Optional[PIL.Image.Image]
Defined on FloatingItem: returns self.image.pil_image if generate_picture_images was set; otherwise falls back to cropping the page raster via DocItem.get_image(). Returns None if no page image is available.

PictureItem.image → Optional[ImageRef]
Populated only when generate_picture_images = True. ImageRef stores mimetype, dpi, size, and a uri (data URL or file path). The PIL image is lazily decoded via ImageRef.pil_image 3.

PictureItem.meta → Optional[PictureMeta]
Holds enrichment results: classification (predicted image type + confidence), description (VLM caption), tabular_chart, and molecule. Populated only if the corresponding pipeline flags (do_picture_classification, do_picture_description, etc.) are enabled 4.

PictureItem.caption_text(doc) → str
Resolves linked caption items and returns concatenated caption text 5.

Iterating all pictures in a document:

for picture in result.document.pictures:
    img = picture.get_image(result.document) # PIL Image or None
    if img:
        img.save(f"picture-{picture.self_ref}.png")
    print(picture.caption_text(result.document))
    if picture.meta and picture.meta.classification:
        print(picture.meta.classification)

See inspect_picture_content.py for traversing child text items within a picture region.

3. Saving and Exporting Images#

Save individual images to disk — call element.get_image(doc).save(fp, "PNG") inside an iterate_items() loop 6.

Save page-level rasters — access page.image.pil_image from doc.pages 7.

Export to Markdown/HTML with embedded or referenced images — use ImageRefMode 8:

from docling_core.types.doc import ImageRefMode

doc.save_as_markdown(path, image_mode=ImageRefMode.EMBEDDED) # base64 inline
doc.save_as_markdown(path, image_mode=ImageRefMode.REFERENCED) # external PNG files
doc.save_as_html(path, image_mode=ImageRefMode.REFERENCED)

Per-item export is also available directly on PictureItem 9:

• picture.export_to_markdown(doc, image_mode=ImageRefMode.EMBEDDED)
• picture.export_to_html(doc, image_mode=ImageRefMode.PLACEHOLDER) (default for HTML)

4. Optional Enrichments#

Enable additional enrichments in PdfPipelineOptions before conversion 10:

Key Source Files#