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 DocxConverterWithOCR in the markitdown-ocr plugin accepted a .docx stream, but the import of its required packages (e.g. mammoth / python-docx) failed at module load time. The stored import exception is re-raised as MissingDependencyException when convert() is called, with a message telling you exactly which pip extra to install. The traceback of the original ImportError is chained via 'from', so the root cause stays visible.

Source

Thrown at packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py:70

        if extension == ".docx":
            return True

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

        return False

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        if _dependency_exc_info is not None:
            raise MissingDependencyException(
                MISSING_DEPENDENCY_MESSAGE.format(
                    converter=type(self).__name__,
                    extension=".docx",
                    feature="docx",
                )
            ) from _dependency_exc_info[1].with_traceback(
                _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:
            # 1. Extract and OCR images — returns raw text per image
            file_stream.seek(0)
            image_ocr_map = self._extract_and_ocr_images(file_stream, ocr_service)

View on GitHub (pinned to fd239d5d2b)

Solutions

pip install 'markitdown[docx]' (or pip install 'markitdown[all]') in the SAME environment that runs the OCR converter
If using markitdown-ocr separately, ensure its declared dependencies (mammoth, etc.) are installed: pip install markitdown-ocr[all]
Verify with: python -c "import mammoth" before re-running the conversion
Check the chained 'from' traceback in the exception to confirm which specific import failed

Example fix

# before
pip install markitdown-ocr
md.convert("doc.docx")  # MissingDependencyException

# after
pip install 'markitdown[docx]' 'markitdown[all]'
md.convert("doc.docx")

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

print(importlib.util.find_spec("mammoth") is not None)

Try / catch

from markitdown import MissingDependencyException

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

Prevention

Pin 'markitdown[all]' (or at least [docx]) in requirements to ship every extra the OCR plugin needs
Add a startup probe that importlib-checks each optional dependency your pipeline uses
Run conversions in the same virtualenv where the converter classes were imported

When it happens

Trigger: Calling convert()/convert_stream() on a .docx file through DocxConverterWithOCR when 'mammoth' (the docx extra) is not installed in the active environment; e.g. pip install markitdown-ocr without extras, then converting a Word document with OCR enabled.

Common situations: Installing markitdown-ocr as a bare dependency in a service image, mixing virtual environments (converter registered in one env, deps in another), or a partial install where the OCR extras were pruned by a slim Docker build.

Related errors

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