microsoft/markitdown · error · MissingDependencyException

Speech transcription requires installing MarkItDown with the

Error message

Speech transcription requires installing MarkItDown with the [audio-transcription] optional dependencies. E.g., `pip install 'markitdown[audio-transcription]'` or `pip install 'markitdown[all]'`

What it means

Audio transcription in MarkItDown delegates to SpeechRecognition and pydub, imported inside a module-level try/except in _transcribe_audio.py. If that import fails, the exc info is cached and transcribe_audio() raises MissingDependencyException with instructions to install the [audio-transcription] extra. The converter path (audio files routed by extension/mimetype) reaches this helper, so converting any recognized audio format without the extra produces this error.

Source

Thrown at packages/markitdown/src/markitdown/converters/_transcribe_audio.py:26

_dependency_exc_info = None
try:
    # Suppress some warnings on library import
    import warnings

    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        warnings.filterwarnings("ignore", category=SyntaxWarning)
        import speech_recognition as sr
        import pydub
except ImportError:
    # Preserve the error and stack trace for later
    _dependency_exc_info = sys.exc_info()


def transcribe_audio(file_stream: BinaryIO, *, audio_format: str = "wav") -> str:
    # Check for installed dependencies
    if _dependency_exc_info is not None:
        raise MissingDependencyException(
            "Speech transcription requires installing MarkItDown with the "
            "[audio-transcription] optional dependencies. E.g., "
            "`pip install 'markitdown[audio-transcription]'` or "
            "`pip install 'markitdown[all]'`"
        ) from _dependency_exc_info[
            1
        ].with_traceback(  # type: ignore[union-attr]
            _dependency_exc_info[2]
        )

    if audio_format in ["wav", "aiff", "flac"]:
        audio_source = file_stream
    elif audio_format in ["mp3", "mp4"]:
        audio_segment = pydub.AudioSegment.from_file(file_stream, format=audio_format)

        audio_source = io.BytesIO()
        audio_segment.export(audio_source, format="wav")
        audio_source.seek(0)

View on GitHub (pinned to fd239d5d2b)

Solutions

Install the extra: pip install 'markitdown[audio-transcription]'
Or: pip install 'markitdown[all]'
On Python 3.13+, also install the audioop shim (pip install audioop-lts) since pydub depends on the removed stdlib audioop module
Ensure ffmpeg is on PATH: transcription of mp3/mp4 goes through pydub, which shells out to ffmpeg

Example fix

# before (Python 3.13, base install)
pip install markitdown
MarkItDown().convert('clip.mp3')  # MissingDependencyException

# after
pip install 'markitdown[audio-transcription]' audioop-lts
# and ensure ffmpeg is available:
sudo apt-get install -y ffmpeg

Defensive patterns

Strategy: try-catch

Validate before calling

from markitdown.converters._transcribe_audio import _dependency_exc_info

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

Try / catch

from markitdown import MarkItDown, MissingDependencyException

try:
    result = MarkItDown().convert("note.mp3")
except MissingDependencyException:
    logger.error("install markitdown[audio-transcription] (plus ffmpeg, and audioop-lts on Python 3.13)")
    raise

Prevention

Install markitdown[audio-transcription] and ffmpeg in environments accepting audio
On Python 3.13+, add the audioop-lts shim for pydub
Startup-probe the transcription dependency and disable audio upload paths when missing

When it happens

Trigger: Calling MarkItDown().convert() on .mp3/.wav/.m4a/.flac files (the audio converter accepts them) without the audio extra installed; or when speech_recognition/pydub are present but import fails (pydub needs audioop, removed in Python 3.13, or ffmpeg-related import errors).

Common situations: Python 3.13 environments where pydub breaks on the removed audioop module; base installs in document-processing services that later receive audio attachments; offline/air-gapped installs where the extra was skipped intentionally but audio files still arrive.

Related errors

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