markitdown

---
name: markitdown
description: Use when converting files, Office documents, media, web content, or archives into Markdown for LLM and text-analysis pipelines.
source: https://github.com/microsoft/markitdown
generated: 2026-07-02T18:42:56.818Z
category: tool
audience: engineers
---

## When to use

- Converting PDF, PowerPoint, Word, Excel, HTML, CSV, JSON, XML, EPub, ZIP, image, audio, or YouTube inputs into Markdown
- Preparing document contents for an LLM while preserving useful structure such as headings, lists, tables, and links
- Choosing optional MarkItDown dependencies, plugins, or Azure-backed converters for higher-quality extraction
- Embedding file-to-Markdown conversion in Python code with a tighter input boundary than a general-purpose CLI call

## Key concepts

### LLM-oriented Markdown

MarkItDown optimizes converted output for downstream LLM and text-analysis workflows, not high-fidelity human-facing document reproduction.

### Format extras

Install only the optional dependency groups needed for the target formats, such as pdf, docx, pptx, xlsx, xls, outlook, az-doc-intel, az-content-understanding, audio-transcription, or youtube-transcription.

### Plugins

Third-party plugins are disabled by default. List installed plugins before use, then explicitly enable plugins only when the task needs them.

### Azure converters

Azure Document Intelligence and Azure Content Understanding can improve extraction for scanned documents, complex tables, audio, video, and structured fields, but each routed conversion may call a billable Azure API.

### Narrow conversion APIs

The broad convert() API can handle local files, remote URIs, and streams. Prefer convert_local(), convert_stream(), or convert_response() when the input source is known.

## API reference

```
pip install 'markitdown[all]'
```

Install MarkItDown with all optional converters enabled.

```
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'
```

```
pip install 'markitdown[pdf, docx, pptx]'
```

Install only the optional dependencies required for selected file formats.

```
pip install 'markitdown[pdf, docx, pptx]'
```

```
markitdown path-to-file.pdf -o document.md
```

Convert a local file to Markdown from the command line.

```
markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown
```

```
markitdown --list-plugins
```

Inspect and enable installed third-party MarkItDown plugins.

```
markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf
```

```
markitdown path-to-file.pdf -d -e "<document_intelligence_endpoint>"
```

Use Azure Document Intelligence for conversion when layout or OCR quality matters.

```
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
```

```
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
```

Use Azure Content Understanding for multimodal conversion or structured extraction.

```
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
```

```
MarkItDown(enable_plugins=False).convert("test.xlsx")
```

Convert content from Python code and read the Markdown text.

```
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)
```

```
MarkItDown(llm_client=client, llm_model="gpt-4o").convert("example.jpg")
```

Use an LLM client for image descriptions in supported converters.

```
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)
```

## Gotchas

- MarkItDown performs I/O with the privileges of the current process, so validate untrusted paths, URIs, and streams before conversion.
- Use the narrowest conversion API that fits the task; avoid broad convert() calls in hosted or server-side paths when only local files or streams are allowed.
- Plugins are disabled by default and should be explicitly enabled only after confirming the installed plugin set.
- Azure Document Intelligence and Content Understanding require configured Azure endpoints and may create billable API calls.
- The output is intended for LLM and text-analysis consumption, so do not treat it as a high-fidelity replacement for document rendering.

---
Generated by SkillMake from https://github.com/microsoft/markitdown on 2026-07-02T18:42:56.818Z.
Verify against source before relying on details.

File: ~/.claude/skills/markitdown/SKILL.md