{"record":{"id":"f38688d74386efa6","repo":"docling-project/docling","slug":"the-beautifulsoup4-and-lxml-packages-are-requi","errorCode":null,"errorMessage":"The 'beautifulsoup4' and 'lxml' packages are required to process JATS files. Install them with `pip install 'docling-slim[format-xml-jats]'`.","messagePattern":"The 'beautifulsoup4' and 'lxml' packages are required to process JATS files\\. Install them with `pip install 'docling-slim\\[format-xml-jats\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/jats_backend.py","lineNumber":159,"sourceCode":"    representation of journal articles in XML format. Several publishers and journal\n    archives provide content in JATS format, including PubMed Central® (PMC), bioRxiv,\n    medRxiv, or Springer Nature.\n\n    Refer to https://jats.nlm.nih.gov for more details on JATS.\n\n    The code from this document backend has been developed by modifying parts of the\n    PubMed Parser library (version 0.5.0, released on 12.08.2024):\n    Achakulvisut et al., (2020).\n    Pubmed Parser: A Python Parser for PubMed Open-Access XML Subset and MEDLINE XML\n      Dataset XML Dataset.\n    Journal of Open Source Software, 5(46), 1979,\n    https://doi.org/10.21105/joss.01979\n    \"\"\"\n\n    @override\n    def __init__(self, in_doc: InputDocument, path_or_stream: BytesIO | Path) -> None:\n        if not _BS4_AVAILABLE:\n            raise ImportError(_INSTALL_HINT) from _BS4_IMPORT_ERROR\n        super().__init__(in_doc, path_or_stream)\n        self.path_or_stream = path_or_stream\n\n        # Initialize the root of the document hierarchy\n        self.root: NodeItem | None = None\n        self.hlevel: int = 0\n        self.valid: bool = False\n        try:\n            if isinstance(self.path_or_stream, BytesIO):\n                self.path_or_stream.seek(0)\n            parser = etree.XMLParser(\n                resolve_entities=False,\n                load_dtd=False,\n                no_network=True,\n                dtd_validation=False,\n            )\n            self.tree: etree._ElementTree = etree.parse(\n                self.path_or_stream, parser=parser","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/jats_backend.py#L141-L177","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\npip install docling-slim\nconv = DocumentConverter().convert(jats_path)  # ImportError\n\n# after\npip install 'docling-slim[format-xml-jats]'\nconv = DocumentConverter().convert(jats_path)","handlingStrategy":"validation","validationCode":"from importlib.util import find_spec\n\ndef jats_dependencies_available() -> bool:\n    return find_spec(\"bs4\") is not None and find_spec(\"lxml\") is not None","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(jats_path)\nexcept ImportError as e:\n    if \"format-xml-jats\" in str(e):\n        raise SystemExit(\"Install first: pip install 'docling-slim[format-xml-jats]'\") from e\n    raise","preventionTips":["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."],"tags":["jats","xml","import-error","dependencies","docling-slim","packaging"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}