File Formats and Conversion Behavior

This reference targets Microsoft MarkItDown 0.1.8. "Built-in" means the converter ships in the markitdown package; some built-ins still require an optional dependency extra.

Installation by Format

# Full built-in feature set
uv pip install "markitdown[all]==0.1.8"

# Common document subset
uv pip install "markitdown[pdf,docx,pptx,xlsx]==0.1.8"

# Minimal package; suitable for core text/HTML/CSV/ZIP/EPUB/IPYNB paths
uv pip install "markitdown==0.1.8"

Built-in Converter Matrix

Formats commonly overstated

• The 0.1.8 built-in ImageConverter accepts JPEG and PNG, not GIF or WebP.
• Built-in PDF conversion extracts a text layer; Tesseract is not part of MarkItDown's PDF path.
• The package does not promise page ranges, bounding boxes, coordinates, or pixel-faithful output.
• JSON and XML are text-based inputs, not schema-aware transformations.
• A successful conversion does not imply complete figure, equation, table, or reading-order recovery.

PDF

Built-in extraction

from markitdown import MarkItDown

result = MarkItDown().convert_local("paper.pdf")
print(result.markdown)

Use for born-digital PDFs where text is selectable. MarkItDown 0.1.5 improved aligned/wide table output and partially numbered lists; 0.1.6 fixed linear memory growth across PDF pages.

Scanned PDFs

Choose one:

1. markitdown-ocr==0.1.1 with an approved vision provider
2. Azure Document Intelligence
3. Azure Content Understanding
4. A local OCR/layout parser when content cannot leave the environment

Do not claim OCR was performed unless the selected path actually supplied it.

Validate

• Reading order in multi-column papers
• Equations, superscripts, and symbols
• Table headers and row alignment
• Figure captions and footnotes
• References and hyperlinks
• Missing pages or empty scanned sections

DOCX

Install:

uv pip install "markitdown[docx]==0.1.8"

Version 0.1.2 added DOCX math-equation rendering. Conversion is semantic, not page-layout preserving.

Validate:

• Heading levels and list nesting
• Tables and merged cells
• OMML equations
• Hyperlinks and image alt text
• Footnotes/endnotes
• Tracked changes and comments

For custom Mammoth mapping:

from markitdown import MarkItDown

converter = MarkItDown(style_map="p[style-name='Abstract'] => blockquote.abstract")
result = converter.convert_local("manuscript.docx")

PPTX

Install:

uv pip install "markitdown[pptx]==0.1.8"

The converter orders shapes to approximate reading order and extracts textual slide content. Optional llm_client, llm_model, and llm_prompt values can describe image content.

Validate:

• Slide order and boundaries
• Speaker notes
• Grouped/overlapping shapes
• Tables and chart labels
• Images containing essential text
• Content conveyed only by position, color, or animation

XLSX and XLS

Install:

uv pip install "markitdown[xlsx,xls]==0.1.8"

The result is useful for textual review and LLM ingestion, but it is not a workbook round trip.

Validate:

• Sheet names and order
• Hidden rows, columns, and sheets
• Merged cells
• Formula text versus cached/displayed values
• Date/number interpretation
• Charts, images, comments, and conditional formatting

The 0.1.8 XLSX converter reads all worksheets (sheet_name=None); hiding a sheet in Excel is not an extraction filter. Inventory sheet visibility before sharing the Markdown and use an explicitly selected workbook copy if only certain sheets belong in the output.

Formula results depend on values cached in the workbook; MarkItDown does not recalculate formulas. Missing or stale caches can yield blank or outdated cells. For trusted workbooks, recalculate and save with a compatible spreadsheet engine when current formula results are required, then compare key cells with the source. For numeric analysis, read the workbook directly with a dataframe or spreadsheet library after using MarkItDown for orientation.

Images

The built-in converter supports .jpg, .jpeg, and .png.

Without an LLM client, output may contain only selected metadata and can be empty when ExifTool is unavailable or the file has no relevant metadata.

from markitdown import MarkItDown

result = MarkItDown(exiftool_path="/opt/homebrew/bin/exiftool").convert_local(
    "figure.png"
)

The path above is illustrative; discover the executable with shutil.which("exiftool") or use its reviewed absolute path. Use only a trusted ExifTool executable. MarkItDown 0.1.3 added a safety requirement for ExifTool 12.24 or later.

Vision descriptions and OCR are external-processing paths; see cloud_and_ocr.md.

Audio

Accepted extensions are .wav, .mp3, .m4a, and .mp4.

uv pip install "markitdown[audio-transcription]==0.1.8"

Install FFmpeg separately for MP3/M4A/MP4 decoding; the Python extra does not supply that executable. WAV can be decoded directly.

The tested SpeechRecognition==3.17.0 legacy recognizer defaults to an HTTP Google Web Speech endpoint. This is not the authenticated Google Cloud Speech-to-Text API; do not send confidential recordings through this path.

The implementation converts supported audio to a SpeechRecognition input and calls recognize_google(). This is not offline transcription. Use a separately reviewed local or approved secure transcription workflow for confidential recordings.

The converter does not provide speaker diarization, timestamps, confidence values, or domain adaptation.

YouTube

uv pip install "markitdown[youtube-transcription]==0.1.8"
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o transcript.md

Behavior:

• Downloads the page
• Extracts title, description, and selected metadata
• Requests an available transcript
• Prefers English, then an available language, with translation fallback

Availability depends on YouTube, the video, geography, cookies/network policy, and transcript permissions.

CSV, JSON, and XML

CSV has a dedicated table converter:

result = MarkItDown().convert_local("measurements.csv")

JSON and XML are generally handled as text-like formats. If downstream work needs validated records, parse with json, defusedxml, or a schema-aware library rather than parsing the generated Markdown.

ZIP and EPUB

ZIP conversion invokes MarkItDown recursively for archive members. Apply:

• Maximum archive size
• Maximum member count
• Maximum nested depth
• Compression-ratio limits
• Per-member type allowlists

Do not use conversion as an archive-security boundary.

EPUB conversion targets textual book structure. DRM-protected or fixed-layout publications may fail or lose essential visual information.

Remote and Special Sources

convert_uri() accepts:

• file:
• data:
• http:
• https:

file: and data: are still potentially dangerous when user-controlled. http: and https: require SSRF, redirect, size, and timeout controls. See security.md.

Azure Document Intelligence Format Set

The 0.1.8 integration supports:

• Documents: DOCX, PPTX, XLSX
• OCR/layout: PDF, JPEG, PNG, BMP, TIFF
• HTML is represented in the enum but is not in the converter's default file-type list

The API version now defaults to the installed SDK choice (2024-11-30 with tested azure-ai-documentintelligence==1.0.2). Document bytes are sent to Azure.

Azure Content Understanding Format Set

The 0.1.8 integration can route:

• Documents: PDF, DOCX, PPTX, XLSX, HTML, TXT, Markdown, RTF, XML
• Email: EML, MSG
• Images: JPEG, PNG, BMP, TIFF, HEIF/HEIC
• Video: MP4, M4V, MOV, AVI, MKV, WebM, FLV, WMV
• Audio: WAV, MP3, M4A, FLAC, OGG, AAC, WMA

Support here means Azure Content Understanding routing, not local built-in parsing. Each routed conversion is an external, potentially billable operation.

Format Hints

When bytes lack a meaningful filename:

from markitdown import MarkItDown, StreamInfo

with open("upload.bin", "rb") as stream:
    result = MarkItDown().convert_stream(
        stream,
        stream_info=StreamInfo(
            extension=".pdf",
            mimetype="application/pdf",
            filename="upload.pdf",
        ),
    )

CLI equivalents:

markitdown < upload.bin -x .pdf -m application/pdf -o output.md

Source Basis

• Official 0.1.8 README: https://github.com/microsoft/markitdown/blob/v0.1.8/README.md
• Built-in converter registry: https://github.com/microsoft/markitdown/blob/v0.1.8/packages/markitdown/src/markitdown/_markitdown.py
• Release history: https://github.com/microsoft/markitdown/releases

• SpeechRecognition 3.17.0 legacy Google request: https://github.com/Uberi/speech_recognition/blob/3.17.0/speech_recognition/recognizers/google.py