microsoft/markitdown · error · MissingDependencyException

{converter} recognized the input as a potential {extension}

Error message

{converter} recognized the input as a potential {extension} file, but the dependencies needed to read {extension} files have not been installed. To resolve this error, include the optional dependency [{feature}] or [all] when installing MarkItDown. For example:

* pip install 'markitdown[{feature}]'
* pip install 'markitdown[all]'
* pip install 'markitdown[{feature}, ...]'
* etc.

What it means

The OCR-enabled XlsxConverterWithOCR accepted an .xlsx stream, but the xlsx dependency import failed when the module was first loaded; the failure was captured in _xlsx_dependency_exc_info. convert() re-raises it as MissingDependencyException naming the [xlsx] extra. The underlying traceback is chained so the true failing import can be seen.

Source

Thrown at packages/markitdown-ocr/src/markitdown_ocr/_xlsx_converter_with_ocr.py:64

        if extension == ".xlsx":
            return True

        if mimetype.startswith(
            "application/vnd.openxmlformats-officedocument.spreadsheetml"
        ):
            return True

        return False

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        if _xlsx_dependency_exc_info is not None:
            raise MissingDependencyException(
                MISSING_DEPENDENCY_MESSAGE.format(
                    converter=type(self).__name__,
                    extension=".xlsx",
                    feature="xlsx",
                )
            ) from _xlsx_dependency_exc_info[1].with_traceback(
                _xlsx_dependency_exc_info[2]
            )  # type: ignore[union-attr]

        # Get OCR service if available (from kwargs or instance)
        ocr_service: Optional[LLMVisionOCRService] = (
            kwargs.get("ocr_service") or self.ocr_service
        )

        if ocr_service:
            # Remove ocr_service from kwargs to avoid duplicate argument error
            kwargs_without_ocr = {k: v for k, v in kwargs.items() if k != "ocr_service"}
            return self._convert_with_ocr(

View on GitHub (pinned to fd239d5d2b)

Solutions

pip install 'markitdown[xlsx]' or 'markitdown[all]' in the environment running the converter
Verify: python -c "import openpyxl"
Read the chained ImportError if the named extra is already installed — it may reveal a deeper import problem (missing system lib, version conflict)

Example fix

# before
pip install markitdown-ocr
md.convert("book.xlsx")  # MissingDependencyException

# after
pip install 'markitdown[xlsx]'
md.convert("book.xlsx")

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

assert importlib.util.find_spec("openpyxl") is not None

Try / catch

from markitdown import MissingDependencyException

try:
    result = md.convert(xlsx_stream, stream_info=StreamInfo(extension=".xlsx"))
except MissingDependencyException as e:
    log.error("xlsx extras missing: %s", e)
    raise

Prevention

Include the [xlsx] extra wherever markitdown-ocr is deployed
Audit slim images for pruned optional packages after multi-stage builds

When it happens

Trigger: Converting an Excel workbook via XlsxConverterWithOCR in an environment where openpyxl (the xlsx extra) is not installed.

Common situations: Slim Docker images that prune optional deps, mismatched virtual environments, or a fresh install of markitdown-ocr without the xlsx extra.

Related errors

AI-assisted analysis of microsoft/markitdown@fd239d5d2b (2026-08-14). Data as JSON: /api/errors/16a96a8f5bf938da. Report an issue: GitHub.