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 DocxConverter raises MissingDependencyException when its convert() method is invoked but the optional libraries needed to parse .docx files (mammoth, and for style maps mammoth without python-docx conflicts) failed to import at module load time. The import failure is captured in _dependency_exc_info at package import, and convert() re-raises this formatted message with install instructions. It means the converter accepted the file (extension .docx or the docx mimetype) but the runtime environment lacks the 'docx' optional extra.

Source

Thrown at packages/markitdown/src/markitdown/converters/_docx_converter.py:66

        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,  # Options to pass to the converter
    ) -> DocumentConverterResult:
        # Check: the dependencies
        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(  # type: ignore[union-attr]
                _dependency_exc_info[2]
            )

        style_map = kwargs.get("style_map", None)
        pre_process_stream = pre_process_docx(file_stream)
        return self._html_converter.convert_string(
            mammoth.convert_to_html(pre_process_stream, style_map=style_map).value,
            **kwargs,
        )

View on GitHub (pinned to fd239d5d2b)

Solutions

1. Install the docx extra: pip install 'markitdown[docx]'
2. Or install all converters at once: pip install 'markitdown[all]'
3. If the extra is already declared installed, verify the import directly: python -c "import mammoth" and reinstall (pip install --force-reinstall mammoth) to fix a broken environment
4. If you distribute an app embedding markitdown, declare markitdown[docx] in your own dependency metadata so users get it automatically

Example fix

# before
pip install markitdown
markitdown document.docx  # MissingDependencyException

# after
pip install 'markitdown[docx]'
markitdown document.docx

from markitdown.converters._docx_converter import _dependency_exc_info

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

def has_docx_support() -> bool:
    """True when the docx optional dependency imported successfully."""
    import markitdown.converters._docx_converter as m
    return m._dependency_exc_info is None

from markitdown import MarkItDown, MissingDependencyException

try:
    result = MarkItDown().convert("doc.docx")
except MissingDependencyException:
    # surface an actionable message to the operator instead of crashing
    logger.error("markitdown docx extra missing: pip install 'markitdown[docx]'")
    raise

When it happens

Trigger: Calling markitdown.convert() (or MarkItDown().convert()) on a stream whose StreamInfo has extension .docx or mimetype application/vnd.openxmlformats-officedocument.wordprocessingml.document, on an installation done via `pip install markitdown` without extras. Also triggered when mammoth is installed but broken (e.g. incompatible Python version, corrupted install), because any ImportError/ModuleNotFoundError captured at module import produces the same exception.

Common situations: Installing the base markitdown package only; using a minimal Docker/CI image that strips optional deps; a transitive dependency conflict that breaks the mammoth import; upgrading Python versions so a pinned mammoth wheel no longer imports.

Related errors

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

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