docling-project/docling · error · ImportError

The 'beautifulsoup4' and 'defusedxml' packages are required

Error message

The 'beautifulsoup4' and 'defusedxml' packages are required to process USPTO patent files. Install them with `pip install 'docling-slim[format-xml-uspto]'`.

What it means

The USPTO patent backend needs beautifulsoup4 and defusedxml, which are optional extras in docling-slim. Its __init__ checks _BS4_AVAILABLE and raises ImportError with the exact pip extra to install, chained to the original import error.

Source

Thrown at docling/backend/xml/uspto_backend.py:114

    ABSTRACT = "ABSTRACT", 2
    CLAIMS = "CLAIMS", 2

    @override
    def __new__(cls, value: str, _) -> Self:
        obj = object.__new__(cls)
        obj._value_ = value
        return obj

    @override
    def __init__(self, _, level: LevelNumber) -> None:
        self.level: LevelNumber = level


class PatentUsptoDocumentBackend(DeclarativeDocumentBackend):
    @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.patent_content: str = ""
        self.parser: PatentUspto | None = None

        try:
            if isinstance(self.path_or_stream, BytesIO):
                while line := self.path_or_stream.readline().decode("utf-8"):
                    if line.startswith("<!DOCTYPE") or line == "PATN\n":
                        self._set_parser(line)
                    self.patent_content += line
            elif isinstance(self.path_or_stream, Path):
                with open(self.path_or_stream, encoding="utf-8") as file_obj:
                    while line := file_obj.readline():
                        if line.startswith("<!DOCTYPE") or line == "PATN\n":
                            self._set_parser(line)
                        self.patent_content += line
        except Exception as exc:

View on GitHub (pinned to 61d76f1ff3)

Solutions

pip install 'docling-slim[format-xml-uspto]'.
Or install the full docling package which bundles the XML backends.
Verify with python -c 'import bs4, defusedxml' after installing.
Add the extra to your requirements/uv config so rebuilds keep it.

Example fix

# before
pip install docling-slim
DocumentConverter().convert(Path("patent.xml"))  # ImportError

# after
pip install 'docling-slim[format-xml-uspto]'
DocumentConverter().convert(Path("patent.xml"))

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec

def uspto_dependencies_available() -> bool:
    return find_spec("bs4") is not None and find_spec("defusedxml") is not None

Try / catch

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

Prevention

Install format extras for every InputFormat you will feed the converter.
Smoke-test backend imports in CI for the formats in your test corpus.
Track dependency changes when adding new document formats to a pipeline.

When it happens

Trigger: Converting a USPTO patent XML (or the legacy aps/plain 'PATN' format) with docling-slim installed without the format-xml-uspto extra; PatentUsptoDocumentBackend.__init__ raises before any parsing.

Common situations: Slim container images for size; processing patent corpora after originally only needing PDF; CI env pinning docling-slim without extras.

Related errors

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