docling-project/docling · error · ImportError

The 'beautifulsoup4' package is required to process HTML fil

Error message

The 'beautifulsoup4' package is required to process HTML files. Install it with `pip install 'docling-slim[format-html]'`.

What it means

HTMLDocumentBackend.__init__ raises ImportError before super().__init__() when beautifulsoup4 (bs4) is unavailable, chaining the original import error. HTML parsing is an optional extra in docling-slim, so this is the documented, actionable signal that the extra is missing.

Source

Thrown at docling/backend/html_backend.py:428

                # Create new paragraph after each segment except the last
                if i < len(sub_texts) - 1:
                    super_list.append(active_annotated_text_list)
                    active_annotated_text_list = AnnotatedTextList()
        if active_annotated_text_list:
            super_list.append(active_annotated_text_list)
        return super_list


class HTMLDocumentBackend(DeclarativeDocumentBackend):
    @override
    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: Union[BytesIO, Path],
        options: Optional[HTMLBackendOptions] = None,
    ):
        if not _BS4_AVAILABLE:
            raise ImportError(_INSTALL_HINT) from _BS4_IMPORT_ERROR
        if options is None:
            options = HTMLBackendOptions()
        super().__init__(in_doc, path_or_stream, options)
        self.options: HTMLBackendOptions
        self.soup: Optional[BeautifulSoup] = None
        self.path_or_stream: Union[BytesIO, Path] = path_or_stream
        self.base_path: Optional[str] = (
            str(options.source_uri) if options.source_uri is not None else None
        )
        self._image_loader = ImageResourceLoader(
            enable_local_fetch=options.enable_local_fetch,
            enable_remote_fetch=options.enable_remote_fetch,
            max_image_data_base64_bytes=options.max_image_data_base64_bytes,
            max_remote_image_bytes=options.max_remote_image_bytes,
            max_redirects=options.max_redirects,
            headers=options.headers,
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install the extra: pip install 'docling-slim[format-html]'
2. Or install full docling which bundles format extras
3. Record required format extras in the deployment manifest

Example fix

# before
pip install docling-slim

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

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

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

When it happens

Trigger: Converting HTML (or any pipeline that instantiates HTMLDocumentBackend, e.g. EPUB content files) in an environment lacking bs4 — typically docling-slim installed without format-html.

Common situations: Slim Docker images; dependency-stripped Lambda layers; installing docling-slim explicitly for size and forgetting which formats are needed.

Related errors

• The 'mail-parser' package is required to process email files
• The 'pylatexenc' package is required to process LaTeX files.
• The 'marko' package is required to process Markdown files. I
• The 'python-oxmsg' package is required to process Outlook .m
• Playwright is required for HTML rendering. Install it with '

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