How to Use MarkItDown: CLI and Python API Guide for Document Conversion

Mar 22, 2026

Purpose

I needed a reliable way to convert various document formats to Markdown. PDFs, Word documents, PowerPoint presentations - they all had different tools, and I was tired of juggling multiple solutions. Then I found MarkItDown from Microsoft. It provides a unified interface for converting documents to Markdown, usable both as a CLI tool and a Python library. This post shows how I installed and used it.

Installation

First, I created a virtual environment. MarkItDown requires Python 3.10 or higher, so I made sure to use a compatible version:

# Using standard Python
python -m venv .venv
source .venv/bin/activate

# Or using uv (faster)
uv venv --python=3.12 .venv
source .venv/bin/activate

Then I installed MarkItDown with all optional dependencies:

pip install 'markitdown[all]'

The [all] extra includes support for PDF, DOCX, XLSX, PPTX, HTML, and image files. If you only need specific formats, you can install selectively:

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

CLI Usage

The simplest way to use MarkItDown is through the command line. I tested it with a PDF file:

markitdown document.pdf

This outputs Markdown to stdout. To save to a file:

markitdown document.pdf -o output.md

You can also pipe content through stdin:

cat document.pdf | markitdown

MarkItDown auto-detects file types, so no additional configuration is needed. I also discovered useful options for plugins:

# List available plugins
markitdown --list-plugins

# Use plugins during conversion
markitdown --use-plugins document.pdf

Python API

For programmatic access, the Python API is straightforward. Here’s how I converted a document:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

The convert() method accepts file paths, URLs, or binary streams. I tested converting from a URL:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://example.com/document.pdf")
print(result.text_content)

For binary streams, remember to open files in binary mode:

from markitdown import MarkItDown

md = MarkItDown()

with open("document.pdf", "rb") as f:
    result = md.convert(f)
    print(result.text_content)

LLM Vision Integration

One powerful feature is LLM vision integration for image descriptions. By providing an OpenAI client, MarkItDown can describe image content:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    llm_client=OpenAI(),
    llm_model="gpt-4o"
)

result = md.convert("image.jpg")
print(result.text_content)

This generates text descriptions for images instead of just extracting metadata.

Common Mistakes

I made a few mistakes when getting started. Here’s what to avoid:

1. Missing optional dependencies

Installing markitdown without extras gives you only basic format support. Always install with [all] or specify the formats you need:

# Wrong - missing dependencies
pip install markitdown

# Right - includes all converters
pip install 'markitdown[all]'

2. Opening files in text mode

When using binary streams, always open in binary mode ("rb"), not text mode:

# Wrong - will fail
with open("document.pdf", "r") as f:
    result = md.convert(f)

# Right - binary mode
with open("document.pdf", "rb") as f:
    result = md.convert(f)

3. Using Python 3.9 or earlier

MarkItDown requires Python 3.10+. If you’re on an older version, upgrade first:

python --version
# Must be 3.10 or higher

Summary

MarkItDown provides a simple, unified interface for document conversion. The CLI handles quick one-off conversions, while the Python API enables integration into pipelines and applications. With auto-detection of file types and optional LLM vision support, it covers most document conversion needs without the complexity of multiple tools.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 MarkItDown GitHub Repository

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!