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 PdfConverterWithOCR accepted a .pdf stream, but the pdf extra's dependencies (e.g. pdfminer.six) failed to import when the module loaded. The failure is captured at import time and re-raised as MissingDependencyException on every convert() call, formatted to name the missing extra. The original ImportError traceback is preserved as the exception cause.

Source

Thrown at packages/markitdown-ocr/src/markitdown_ocr/_pdf_converter_with_ocr.py:165

        if extension == ".pdf":
            return True

        if mimetype.startswith("application/pdf") or mimetype.startswith(
            "application/x-pdf"
        ):
            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=".pdf",
                    feature="pdf",
                )
            ) 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: LLMVisionOCRService | None = (
            kwargs.get("ocr_service") or self.ocr_service
        )

        # Read PDF into BytesIO
        file_stream.seek(0)
        pdf_bytes = io.BytesIO(file_stream.read())

View on GitHub (pinned to fd239d5d2b)

Solutions

pip install 'markitdown[pdf]' (or 'markitdown[all]') into the runtime environment
Confirm the import works: python -c "import pdfminer"
If the chained ImportError shows a different package, install that package directly or fix the broken install (pip install --force-reinstall)

Example fix

# before
pip install markitdown-ocr
md.convert("scan.pdf")  # MissingDependencyException

# after
pip install 'markitdown[pdf]'
md.convert("scan.pdf")

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

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

Try / catch

from markitdown import MissingDependencyException

try:
    result = md.convert(pdf_stream, stream_info=StreamInfo(extension=".pdf"))
except MissingDependencyException:
    # fall back to non-OCR PdfConverter or reject the job with a clear message
    raise

Prevention

Declare the [pdf] extra in the deployment manifest, not just core markitdown
Smoke-test one PDF conversion in CI to catch missing extras before release
Keep the chained __cause__ in logs — it names the exact failing import

When it happens

Trigger: Converting a PDF via PdfConverterWithOCR (convert, convert_uri with a .pdf URL, or convert_stream) in an environment where the [pdf] extra was never installed.

Common situations: CI pipelines that pip install markitdown-ocr without extras, minimized containers that strip optional deps, or upgrading markitdown in an env where the old extras were pinned to an incompatible version and silently dropped.

Related errors

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