docling-project/docling · error · RuntimeError

LibreOffice is required to convert a .{source_suffix} file t

Error message

LibreOffice is required to convert a .{source_suffix} file to .{target_suffix}. Install LibreOffice and make sure it is on PATH.

What it means

The convert_with_soffice helper in docling.backend.docx.drawingml.utils raises this RuntimeError when it needs to run a LibreOffice conversion (e.g. docx->pdf or pptx->pdf to rasterize DrawingML/shape content) but get_libreoffice_cmd() returned None. It names the exact source and target suffixes involved and tells you to install LibreOffice and put it on PATH. Unlike error 11 this check is passive (no smoke test) — it fires before any subprocess is spawned.

Source

Thrown at docling/backend/docx/drawingml/utils.py:112

        source: Path to the source file, or a ``BytesIO`` with its contents.
        source_suffix: File extension of the source format without leading dot
            (e.g. ``"doc"``, ``"xls"``, ``"ppt"``).  Required when *source* is
            a ``BytesIO`` so the temp file gets the right name; ignored for
            ``Path`` inputs (the path's own suffix is used instead).
        target_suffix: Target extension without leading dot (``"docx"``,
            ``"xlsx"``, or ``"pptx"``).
        timeout_s: Timeout in seconds for the LibreOffice subprocess.

    Returns:
        A ``BytesIO`` buffer with the converted file contents.

    Raises:
        RuntimeError: When LibreOffice is not installed, the subprocess fails,
            or the expected output file is not produced.
    """
    libreoffice_cmd = get_libreoffice_cmd()
    if libreoffice_cmd is None:
        raise RuntimeError(
            f"LibreOffice is required to convert a .{source_suffix} file to "
            f".{target_suffix}. Install LibreOffice and make sure it is on PATH."
        )

    tmp_dir = Path(mkdtemp())
    try:
        if isinstance(source, BytesIO):
            source.seek(0)
            input_path = tmp_dir / f"input.{source_suffix}"
            input_path.write_bytes(source.read())
        else:
            input_path = source

        with _isolated_libreoffice_profile() as profile_arg:
            subprocess.run(
                [
                    libreoffice_cmd,
                    profile_arg,

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install LibreOffice and ensure soffice is on PATH (apt-get install -y libreoffice / brew install --cask libreoffice); verify with soffice --version in the same shell/environment that runs docling.
In containers, bake LibreOffice into the image rather than installing at runtime.
If you cannot install LibreOffice, preprocess files to strip drawings, or accept degraded output by disabling the drawing-conversion feature if the calling option allows it.
Confirm the binary name: some distros ship only 'libreoffice' or only 'soffice'; symlink if needed (ln -s /usr/bin/libreoffice /usr/local/bin/soffice).

Example fix

# before
$ python -c "from docling.document_converter import DocumentConverter; DocumentConverter().convert('chart_report.docx')"
RuntimeError: LibreOffice is required to convert a .docx file to .pdf.

# after
$ sudo apt-get update && sudo apt-get install -y libreoffice
$ soffice --version  # verify discoverable
$ python -c "from docling.document_converter import DocumentConverter; DocumentConverter().convert('chart_report.docx')"

Defensive patterns

Strategy: validation

Validate before calling

import shutil, os

def soffice_on_path() -> bool:
    return (shutil.which("libreoffice") is not None
            or shutil.which("soffice") is not None
            or os.path.isfile("/Applications/LibreOffice.app/Contents/MacOS/soffice"))

# gate the feature before converting drawing-heavy files
assert soffice_on_path(), "LibreOffice required for DrawingML rasterization"

Try / catch

try:
    result = conv.convert(docx_path)
except RuntimeError as e:
    if "LibreOffice is required" in str(e):
        install_or_skip(docx_path)  # env problem: fix image/host, not the file
    else:
        raise

Prevention

Install LibreOffice in slim containers when processing Office files with charts/shapes.
Check the exact suffixes in the message to identify which conversion stage needed LibreOffice.
Keep an environment probe (shutil.which) in deployment smoke tests.

When it happens

Trigger: Converting DOCX (or XLSX/PPTX) files that contain drawings/shapes/images requiring rasterization, on a host without libreoffice/soffice discoverable via PATH or the default macOS app path. The suffixes in the message tell you which conversion stage needed it (commonly source docx, target pdf).

Common situations: Same environments as the 'Libreoffice not found' error: slim containers, minimal CI images, servers without an office suite. Files with embedded charts, SmartArt, or shape-heavy headers trigger the LibreOffice path, so the same pipeline works for plain DOCX but fails on drawing-rich ones.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/21b479e321b74d9e. Report an issue: GitHub.