docling-project/docling · error · ImportError

The 'marko' package is required to process Markdown files. I

Error message

The 'marko' package is required to process Markdown files. Install it with `pip install 'docling-slim[format-markdown]'`.

What it means

MarkdownDocumentBackend.__init__ raises ImportError before super().__init__() when marko is unavailable, chaining the original import error. The check runs first specifically so a missing dependency yields this actionable message instead of a NameError when marko is first dereferenced during parsing.

Source

Thrown at docling/backend/md_backend.py:230

        )
        shortened_text, count = pattern.subn(r"\1- ", markdown_text)

        if count > 0:
            warnings.warn("Detected potentially incorrect Markdown, correcting...")

        return shortened_text

    @override
    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: Union[BytesIO, Path],
        options: Optional[MarkdownBackendOptions] = None,
    ):
        # Raised first so a missing optional dependency gives an actionable
        # message rather than a NameError when marko is dereferenced below.
        if not _MARKO_AVAILABLE:
            raise ImportError(_INSTALL_HINT) from _MARKO_IMPORT_ERROR
        if options is None:
            options = MarkdownBackendOptions()
        super().__init__(in_doc, path_or_stream, options)

        _log.debug("Starting MarkdownDocumentBackend...")

        # Markdown file:
        self.path_or_stream = path_or_stream
        self.valid = True
        self.markdown = ""  # To store original Markdown string

        self.in_table = False
        self.in_pipeless_table = False
        self.md_table_buffer: list[str] = []
        self._html_blocks: int = 0
        self._image_loader: Optional[ImageResourceLoader] = None

        try:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the extra: pip install 'docling-slim[format-markdown]'
Or install the full docling package
Verify the extra is present in Docker/CI dependency specs

Example fix

# before
pip install docling-slim

# after
pip install 'docling-slim[format-markdown]'

Defensive patterns

Strategy: validation

Validate before calling

try:
    import marko  # noqa: F401
except ImportError:
    raise RuntimeError("Install: pip install 'docling-slim[format-markdown]'")

Try / catch

try:
    result = converter.convert(src)
except ImportError as exc:
    if 'marko' in str(exc):
        install_or_skip('docling-slim[format-markdown]')
    raise

Prevention

Declare the format-markdown extra in dependency specs
Probe optional imports at startup for all accepted formats

When it happens

Trigger: Converting Markdown files (InputFormat.MARKDOWN) with docling-slim installed but the format-markdown extra (marko) missing.

Common situations: Slim installs chosen for image size; enabling Markdown conversion later without updating requirements; CI environments built from stale lockfiles.

Related errors

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