docling-project/docling · error · ImportError

The 'arelle-release' package is required to process XBRL doc

Error message

The 'arelle-release' package is required to process XBRL documents. Please install it using `pip install 'docling-slim[format-xml-xbrl]'`

What it means

The XBRL backend requires the arelle-release package (Arelle XBRL toolkit), an optional extra in docling-slim. Its __init__ checks _XBRL_AVAILABLE and raises ImportError with the install hint chained to the original import failure, before touching the document.

Source

Thrown at docling/backend/xml/xbrl_backend.py:93

    Refer to https://www.xbrl.org for more details on XBRL. In particular, refer to
    https://www.xbrl.org/Specification/taxonomy-package/REC-2016-04-19/taxonomy-package-REC-2016-04-19.html
    for details on how to provide a taxonomy package.

    This backend leverages the Arelle library for XBRL processing.
    """

    @override
    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: BytesIO | Path,
        options: XBRLBackendOptions | None = None,
    ) -> None:
        if options is None:
            options = XBRLBackendOptions()
        # Check if arelle is available before proceeding
        if not _XBRL_AVAILABLE:
            raise ImportError(
                "The 'arelle-release' package is required to process XBRL documents. "
                "Please install it using `pip install 'docling-slim[format-xml-xbrl]'`"
            ) from _XBRL_IMPORT_ERROR

        super().__init__(in_doc, path_or_stream)
        self.options: XBRLBackendOptions = options
        self.model_xbrl: ModelXbrl | None = None
        self._kv_idx: int = 0
        self._cells: list[GraphCell] = []
        self._links: list[GraphLink] = []
        self._hierarchy_cell_ids: dict[str, int] = {}
        self._fact_cell_ids: dict[str, list[int]] = defaultdict(list)
        self._created_links: set[tuple[int, int]] = set()

        try:
            if (
                not self.options.enable_local_fetch
                and not self.options.enable_remote_fetch

View on GitHub (pinned to 61d76f1ff3)

Solutions

pip install 'docling-slim[format-xml-xbrl]'.
Or install the full docling meta-package.
Verify with python -c 'import arelle' after installation.
Pin the extra in your lock/requirements file to survive image rebuilds.

Example fix

# before
pip install docling-slim
DocumentConverter().convert(Path("report.xbrl"))  # ImportError

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

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec

def xbrl_dependencies_available() -> bool:
    return find_spec("arelle") is not None

Try / catch

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

Prevention

Install extras per format at environment build time.
Import-smoke each backend in CI for formats in your corpus.
Pin the extra in requirements/uv so rebuilds keep XBRL support.

When it happens

Trigger: Converting an XBRL document (instance or taxonomy-backed) with docling-slim lacking format-xml-xbrl; XBRLBackend.__init__ raises immediately regardless of the document's content.

Common situations: Slim deployments (Lambda/containers) that only needed PDF initially; adding financial-report processing later; arelle-release failing to install on exotic platforms.

Related errors

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