docling-project/docling · error · ImportError

The 'beautifulsoup4' and 'lxml' packages are required to pro

Error message

The 'beautifulsoup4' and 'lxml' packages are required to process JATS files. Install them with `pip install 'docling-slim[format-xml-jats]'`.

What it means

The JATS (PubMed XML) backend needs beautifulsoup4 and lxml, which are optional dependencies in docling-slim. On __init__ it checks _BS4_AVAILABLE and raises ImportError with this install hint chained to the original import failure. Docling-slim users hitting a JATS document without the extras get this immediately.

Source

Thrown at docling/backend/xml/jats_backend.py:159

    representation of journal articles in XML format. Several publishers and journal
    archives provide content in JATS format, including PubMed Central® (PMC), bioRxiv,
    medRxiv, or Springer Nature.

    Refer to https://jats.nlm.nih.gov for more details on JATS.

    The code from this document backend has been developed by modifying parts of the
    PubMed Parser library (version 0.5.0, released on 12.08.2024):
    Achakulvisut et al., (2020).
    Pubmed Parser: A Python Parser for PubMed Open-Access XML Subset and MEDLINE XML
      Dataset XML Dataset.
    Journal of Open Source Software, 5(46), 1979,
    https://doi.org/10.21105/joss.01979
    """

    @override
    def __init__(self, in_doc: InputDocument, path_or_stream: BytesIO | Path) -> None:
        if not _BS4_AVAILABLE:
            raise ImportError(_INSTALL_HINT) from _BS4_IMPORT_ERROR
        super().__init__(in_doc, path_or_stream)
        self.path_or_stream = path_or_stream

        # Initialize the root of the document hierarchy
        self.root: NodeItem | None = None
        self.hlevel: int = 0
        self.valid: bool = False
        try:
            if isinstance(self.path_or_stream, BytesIO):
                self.path_or_stream.seek(0)
            parser = etree.XMLParser(
                resolve_entities=False,
                load_dtd=False,
                no_network=True,
                dtd_validation=False,
            )
            self.tree: etree._ElementTree = etree.parse(
                self.path_or_stream, parser=parser

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the extra: pip install 'docling-slim[format-xml-jats]'.
Or switch to the full package: pip install docling (bundles XML format backends).
If using uv: uv add 'docling-slim[format-xml-jats]'.
Verify lxml actually imports afterwards (python -c 'import lxml, bs4') since a broken build can leave the flag false.

Example fix

# before
pip install docling-slim
conv = DocumentConverter().convert(jats_path)  # ImportError

# after
pip install 'docling-slim[format-xml-jats]'
conv = DocumentConverter().convert(jats_path)

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec

def jats_dependencies_available() -> bool:
    return find_spec("bs4") is not None and find_spec("lxml") is not None

Try / catch

try:
    result = converter.convert(jats_path)
except ImportError as e:
    if "format-xml-jats" in str(e):
        raise SystemExit("Install first: pip install 'docling-slim[format-xml-jats]'") from e
    raise

Prevention

Declare the format extras you need in your environment spec, not ad hoc.
For containers, smoke-test each format backend import after build.
Prefer the full docling package when multiple XML formats are in scope.

When it happens

Trigger: Using docling-slim (not the full docling package) and converting a JATS XML document; JatsBackend.__init__ runs, _BS4_AVAILABLE is False because beautifulsoup4/lxml are not installed, and ImportError(_INSTALL_HINT) is raised.

Common situations: Docker images built on docling-slim to save space; adding JATS support later without reinstalling; environments where lxml compilation is missing so the extra silently failed to install.

Related errors

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