Skip to content
Get packs

Guide · Open source

How to use MarkItDown: convert PDFs and Office files to Markdown

Updated · written with AI from the project's own documentation and checked against our catalogue data

MarkItDown is an open-source Python tool from Microsoft that converts files such as PDFs, Word, Excel and PowerPoint documents, HTML and more into Markdown text. This guide shows how to install it, run conversions from the command line and from Python, and choose the optional extras you need. By the end you will be able to turn a file into Markdown and know where the tool fits and where it does not.

MarkItDownmicrosoft/markitdown · ★ 193k · MIT

Quick start

  1. 1Check your Python version. Confirm you have Python 3.10 through 3.14 installed.
  2. 2Create a virtual environment. Create and activate a venv so the dependencies stay isolated.
  3. 3Install MarkItDown. Run pip install 'markitdown[all]' or install only the extras you need.
  4. 4Convert a file. Run markitdown on a file and send the output to a .md file with -o.
  5. 5Use the Python API. Import MarkItDown, call convert, and read result.markdown.
  6. 6Enable plugins if needed. List plugins with --list-plugins and turn them on with --use-plugins.

What MarkItDown does and who it is for

MarkItDown is a lightweight Python utility for converting various files to Markdown, mainly for use with LLMs and text analysis pipelines. It keeps document structure such as headings, lists, tables and links. The README says the output is meant for text analysis tools and may not be the best option for high-fidelity conversions meant for human reading.

  • Developers building LLM or text analysis pipelines that need document text
  • People converting a batch of PDFs or Office files to Markdown from the command line
  • Projects that want a Python library for document conversion inside existing code

Check Python and set up a virtual environment

MarkItDown requires Python 3.10 through 3.14. The README recommends a virtual environment to avoid dependency conflicts, and shows the standard venv commands below.

  • Standard Python: create the environment with venv, then activate it.
  • uv users: use uv venv, and install packages with uv pip install rather than plain pip.
  • Anaconda users: create a named environment with conda.
python -m venv .venv source .venv/bin/activate

Install MarkItDown with pip

Install all optional dependencies with pip. The README uses this command for the simplest setup. If you prefer to install only some formats, you can choose extras individually.

pip install 'markitdown[all]'

Convert a file from the command line

Pass a file path to the markitdown command and redirect the output to a .md file, or use -o to name the output file. You can also pipe a file into the command.

  • Redirect output: markitdown path-to-file.pdf > document.md
  • Name the output file: markitdown path-to-file.pdf -o document.md
  • Pipe content in: cat path-to-file.pdf | markitdown
markitdown path-to-file.pdf -o document.md

Convert files in Python

Import MarkItDown, call convert on a file path, and read the markdown property of the result. The README advises calling the narrowest convert_* function you need, such as convert_stream() or convert_local(), when you process untrusted input.

  • Use convert for a quick file path conversion.
  • Use the narrower convert_* functions in untrusted environments.
from markitdown import MarkItDown md = MarkItDown() result = md.convert("path-to-file.pdf") print(result.markdown)

Install only the formats you need

The [all] option installs every optional dependency. You can instead install extras for specific formats. The README lists these extras: pptx, docx, xlsx, xls, pdf, outlook, az-doc-intel, az-content-understanding, audio-transcription and youtube-transcription.

  • [pdf] for PDF files
  • [docx] for Word files
  • [pptx] for PowerPoint files
  • [xlsx] for Excel files
  • [xls] for older Excel files
  • [outlook] for Outlook messages
  • [audio-transcription] for wav and mp3 audio
  • [youtube-transcription] for YouTube video transcription
pip install 'markitdown[pdf, docx, pptx]'

Use plugins and security settings carefully

Third-party plugins are disabled by default. You can list installed plugins, then enable them for a run. The README also notes that MarkItDown performs I/O with the privileges of the current process, so sanitize inputs in untrusted environments.

  • List installed plugins with --list-plugins.
  • Enable plugins for one run with --use-plugins.
  • The markitdown-ocr plugin adds LLM-based OCR for PDF, DOCX, PPTX and XLSX embedded images, and is skipped if no llm_client is given.
markitdown --list-plugins markitdown --use-plugins path-to-file.pdf

What people use it for

  • Preparing a folder of PDF reports as Markdown text for an LLM prompt
  • Converting Word or PowerPoint material into text for a search or analysis pipeline
  • Adding document conversion to an existing Python application as a library
  • Turning HTML pages or CSV, JSON and XML files into Markdown for review

Frequently asked questions

Is MarkItDown free to use?

MarkItDown is released under the MIT licence, as listed on the project page. The Azure Document Intelligence and Azure Content Understanding options are billable Azure API calls, while the built-in converters run on local compute.

What Python version does MarkItDown need?

MarkItDown requires Python 3.10 through 3.14. The README recommends running it inside a virtual environment.

How do I install MarkItDown?

Run pip install 'markitdown[all]' to install it with all optional dependencies. You can also install only the extras you need, such as 'markitdown[pdf, docx, pptx]'.

Can MarkItDown convert PDFs and Word files to Markdown?

Yes. The README lists PDF, Word, PowerPoint and Excel among supported formats. Run markitdown on the file, or call convert in Python, and read the markdown output.

Does MarkItDown support video?

The built-in converters do not support video. According to the README, only the Azure Content Understanding option supports video conversion.

How does MarkItDown compare to textract or Pandoc?

The README describes MarkItDown as most comparable to textract, with a focus on preserving document structure as Markdown. Pandoc and pdfplumber are other projects people compare it with, but this guide does not benchmark them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MarkItDown suits developers and teams who need document text in Markdown for LLM or text analysis work, and who want a command-line tool or Python library for it. If you need high-fidelity layouts for people to read, or video conversion without Azure, pick another tool. Run it only on inputs you trust, because it uses the permissions of the current process.

Install options & downloads