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

MarkItDown's PdfConverter raises MissingDependencyException when convert() is called but pdfminer.six (and friends in the [pdf] extra) failed to import at module load. The converter accepted the stream as a PDF (extension .pdf or mimetype application/pdf, also matching the zip/pdf magic sniffing), then hits the dependency guard. Note this converter is also used as a fallback for unknown binary streams containing PDF signatures, so the error can appear even when you did not explicitly request PDF handling.

Source

Thrown at packages/markitdown/src/markitdown/converters/_pdf_converter.py:527

        extension = (stream_info.extension or "").lower()

        if extension in ACCEPTED_FILE_EXTENSIONS:
            return True

        for prefix in ACCEPTED_MIME_TYPE_PREFIXES:
            if mimetype.startswith(prefix):
                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]

        assert isinstance(file_stream, io.IOBase)

        # Read file stream into BytesIO for compatibility with pdfplumber
        pdf_bytes = io.BytesIO(file_stream.read())

        try:
            # Single pass: check every page for form-style content.
            # Pages with tables/forms get rich extraction; plain-text
            # pages are collected separately. page.close() is called

View on GitHub (pinned to fd239d5d2b)

Solutions

Install the pdf extra: pip install 'markitdown[pdf]'
Or install all extras: pip install 'markitdown[all]'
Confirm the import: python -c "import pdfminer"; fix/reinstall if it errors
For size-constrained deployments, install only the extras matching the formats you actually accept and reject other formats upstream

Example fix

# before
pip install markitdown
MarkItDown().convert("report.pdf")  # MissingDependencyException

# after
pip install 'markitdown[pdf]'
MarkItDown().convert("report.pdf")

Defensive patterns

Strategy: try-catch

Validate before calling

from markitdown.converters._pdf_converter import _dependency_exc_info

def can_convert_pdf() -> bool:
    return _dependency_exc_info is None

Try / catch

from markitdown import MarkItDown, MissingDependencyException

try:
    result = MarkItDown().convert("doc.pdf")
except MissingDependencyException:
    logger.error("install markitdown[pdf] to process PDFs")
    raise

Prevention

Install markitdown[pdf] (or [all]) in deployments that may see PDFs — remember sniffed PDFs reach this converter even without a .pdf extension
Startup-probe the pdf dependency before serving traffic
Pin pdfminer.six-compatible dependency versions to avoid import breakage

When it happens

Trigger: Calling convert() on a .pdf file, a stream with mimetype application/pdf, or a sniffed PDF magic header (%PDF-) when markitdown was installed without the [pdf] extra; or when pdfminer_six is installed but its import raises (version conflicts with cryptography, broken installs).

Common situations: Minimal installs in Lambda/CI where package size matters and extras were skipped; processing mixed document folders where a PDF slips in; a pip resolver downgrade of pdfminer.six breaking its imports after another package pinned protobuf/cryptography.

Related errors

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