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

XlsxConverter raises MissingDependencyException when convert() runs but the import of openpyxl/pandas for .xlsx handling failed at module load (_xlsx_dependency_exc_info). accepts() matched .xlsx extension or the xlsx mimetype, then the guard fires with instructions to install the [xlsx] extra. Note the sibling .xls converter in the same file has its own separate guard and xlrd dependency.

Source

Thrown at packages/markitdown/src/markitdown/converters/_xlsx_converter.py:71

        if extension in ACCEPTED_XLSX_FILE_EXTENSIONS:
            return True

        for prefix in ACCEPTED_XLSX_MIME_TYPE_PREFIXES:
            if mimetype.startswith(prefix):
                return True

        return False

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,  # Options to pass to the converter
    ) -> DocumentConverterResult:
        # Check the dependencies
        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(  # type: ignore[union-attr]
                _xlsx_dependency_exc_info[2]
            )

        sheets = pd.read_excel(file_stream, sheet_name=None, engine="openpyxl")
        md_content = ""
        for s in sheets:
            md_content += f"## {s}\n"
            html_content = sheets[s].to_html(index=False)
            md_content += (
                self._html_converter.convert_string(

View on GitHub (pinned to fd239d5d2b)

Solutions

  1. Install the extra: pip install 'markitdown[xlsx]'
  2. Or: pip install 'markitdown[all]'
  3. Verify imports: python -c "import pandas, openpyxl"; reinstall (pip install --force-reinstall pandas openpyxl) if it fails
  4. Add markitdown[xlsx] (or [all]) to your application's dependency list so deployments always include it

Example fix

# before
pip install markitdown
MarkItDown().convert('budget.xlsx')  # MissingDependencyException

# after
pip install 'markitdown[xlsx]'
MarkItDown().convert('budget.xlsx')
Defensive patterns

Strategy: try-catch

Validate before calling

from markitdown.converters._xlsx_converter import _xlsx_dependency_exc_info

def can_convert_xlsx() -> bool:
    return _xlsx_dependency_exc_info is None

Try / catch

from markitdown import MarkItDown, MissingDependencyException

try:
    result = MarkItDown().convert("sheet.xlsx")
except MissingDependencyException:
    logger.error("install markitdown[xlsx] to process Excel workbooks")
    raise

Prevention

When it happens

Trigger: Calling convert() on a stream with extension .xlsx or mimetype application/vnd.openxmlformats-officedocument.spreadsheetml.sheet when markitdown lacks the [xlsx] extra; or openpyxl/pandas import failure (pandas ABI mismatch after a Python upgrade, corrupted wheels).

Common situations: Spreadsheet-ingestion services on base markitdown; environments where pandas was compiled for a different Python minor version and now raises ImportError; slim Docker images omitting extras to reduce size.

Related errors

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