Microsoft PDF to Markdown: MarkItDown Guide (2026)

November 11, 2026 · 10 min read

Microsoft PDF to Markdown With MarkItDown: Install, Convert, Clean Up

Microsoft PDF to Markdown conversion runs through MarkItDown, Microsoft's free, MIT-licensed Python library and command-line tool. Install it with pip install 'markitdown[pdf]', then run markitdown file.pdf -o file.md. Expect plain text with no # headings, plus pipe tables on table-like pages, so plan a cleanup pass before people read it.

How Microsoft PDF to Markdown Conversion Works in MarkItDown

MarkItDown is an open-source converter from Microsoft that turns PDF, Word, PowerPoint, Excel, HTML and other files into Markdown. Our Word to Markdown guide covers its Word path. Per the README, the output targets LLMs and text analysis tools and may not suit high-fidelity conversions for human readers. That goal explains most of what you'll see from a PDF.

The PDF converter in version 0.1.9 has a main path and a fallback. First it opens every page with pdfplumber and checks whether the words line up in columns, the way an invoice or a form does. Pages that pass come out with Markdown pipe tables, and the rest come out as plain text. If no page passes, the whole file goes through pdfminer.six's plain text extractor instead.

Neither path looks at font size or weight. So a PDF's title and section headings arrive as ordinary lines, bold and italic disappear, embedded images are skipped and link targets are lost. There's no OCR either, which matters for scans (covered below).

Installing MarkItDown for PDF Conversion

MarkItDown 0.1.9 needs Python 3.10 through 3.14, per its PyPI page. Install it inside a virtual environment, as the README recommends, and include the pdf extra:

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

The [pdf] extra pulls in pdfminer.six and pdfplumber. Use 'markitdown[all]' if you also convert Word, Excel or PowerPoint files. A plain pip install markitdown still installs without it. The first PDF then fails with a FileConversionException that wraps a MissingDependencyException and tells you to add [pdf]. We hit that exact error in testing.

The source lives in the microsoft/markitdown repository on GitHub, which also ships a Dockerfile. The README doesn't point to a prebuilt image. Clone the repo and build it yourself:

git clone https://github.com/microsoft/markitdown.git
cd markitdown
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < report.pdf > report.md

That last line reads the PDF from standard input and writes Markdown to report.md, without Python on your host.

Converting a PDF From the MarkItDown Command Line

The markitdown command takes a file name and prints Markdown to standard output. Add -o to write a file instead, or pipe the PDF in:

markitdown report.pdf -o report.md
markitdown report.pdf > report.md
cat report.pdf | markitdown

All three produce the same Markdown; only the destination differs. The CLI converts one file per call, so use a shell loop for a folder of PDFs:

for f in *.pdf; do
  markitdown "$f" -o "${f%.pdf}.md"
done

Each report.pdf becomes report.md next to it. The command exits with an error on a file it can't read, so check the output count against the input count after a large batch.

Calling the MarkItDown Python API in a Pipeline

In Python, create one MarkItDown object and reuse it. The README's security section warns that convert() is deliberately permissive: it accepts local paths, remote URLs and byte streams. When you only read local files, call convert_local() instead, and validate any path a user supplies.

from pathlib import Path
from markitdown import MarkItDown, MarkItDownException

md = MarkItDown(enable_plugins=False)
out = Path("markdown")
out.mkdir(exist_ok=True)

for pdf in sorted(Path("pdfs").glob("*.pdf")):
    try:
        result = md.convert_local(pdf)
    except MarkItDownException as err:
        print(f"skipped {pdf.name}: {err}")
        continue
    (out / f"{pdf.stem}.md").write_text(result.markdown, encoding="utf-8")

This writes one .md file per PDF into markdown/ and logs any file that fails instead of stopping the batch. MarkItDownException is the base class for the library's conversion errors. The text sits on result.markdown. Older tutorials use result.text_content, which still works but is now a soft-deprecated alias.

For uploads or files held in memory, pass a binary stream to convert_stream(). Add a StreamInfo hint so it knows the format. The older file_extension argument is deprecated in the source.

Here's a stream read from an open file:

from markitdown import StreamInfo

with open("invoice.pdf", "rb") as fh:
    result = md.convert_stream(fh, stream_info=StreamInfo(extension=".pdf"))
print(result.markdown)

If you came looking for a PDF to Markdown API, note that MarkItDown is a library, not a hosted service. The README lists web servers and REST APIs as out of scope for the repo, so you wrap it in your own service if you need one. Once you have the text, you'll usually split it into chunks for a model. Our explainer on Markdown in AI tools covers why models handle the format well.

Does MarkItDown Keep Headings and Tables From a PDF?

Tables, sometimes. Headings, no. We built two test PDFs with ReportLab and ran MarkItDown 0.1.9 on Python 3.13. The first was a one-page support report with a title, three section headings, a bulleted list and a small table. Here's the complete output:

Q3 Support Report

Summary

Ticket volume fell 12 percent after the help center update.

Top issues

Password resets
Invoice downloads
Export timeouts

Response times

Channel Median first reply Tickets

Email

Chat

Phone

4 h

3 min

1 min

1,240

2,815

390

(cid:127)
(cid:127)
(cid:127)

This page didn't pass the column check, so pdfminer.six read it as prose. Headings became plain lines and the bold "12 percent" lost its emphasis. The table was read one column at a time, separating each channel from its numbers. The three bullet glyphs turned up at the end as (cid:127) placeholders, which pdfminer prints for characters it can't map to Unicode.

The second PDF was an invoice: a short title above a four-column table. That page passed, and MarkItDown returned a clean pipe table:

Invoice 1042
| Item           | Qty | Unit price | Total  |
| -------------- | --- | ---------- | ------ |
| Hosting plan   | 1   | 120.00     | 120.00 |
| Extra storage  | 3   | 15.00      | 45.00  |
| Support hours  | 4   | 60.00      | 240.00 |
| Domain renewal | 2   | 12.00      | 24.00  |
|                |     | Subtotal   | 429.00 |

Some cleanup is easy to script. This line strips the (cid:NNN) placeholder lines before you save the file:

import re

clean = re.sub(r"^\(cid:\d+\)\s*\n?", "", result.markdown, flags=re.M)

That's the honest limitation: for invoices and forms the output is usable as is, but a report or manual needs hand cleanup before a person reads it. Add # headings, rebuild lists and reassemble any table that came out column by column. Here's the first report after that cleanup. Edit the Markdown and the preview updates as you type:

Q3 Support Report

Summary

Ticket volume fell 12 percent after the help center update.

Top issues

  • Password resets
  • Invoice downloads
  • Export timeouts

Response times

Channel Median first reply Tickets
Email 4 h 1,240
Chat 3 min 2,815
Phone 1 min 390
71 words324 characters19 lines
Markdown

Does MarkItDown Work on Scanned PDFs?

Not on its own. The built-in converter only reads a PDF's text layer, so an image-only scan gives you little or nothing. You have three ways to add OCR, and each one sends your pages to a model or cloud service.

  • The markitdown-ocr plugin. Run pip install markitdown-ocr openai, then create MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o"). It sends embedded images, and each page of a scanned PDF rendered as an image, to that vision model. A hosted provider bills you for the usage. Without an llm_client, the README says OCR is silently skipped.
  • Azure Document Intelligence. Install 'markitdown[az-doc-intel]' and run markitdown scan.pdf -o scan.md -d -e "<endpoint>". Each request is a billable Azure call, and add-ons such as high-resolution OCR cost extra.
  • Azure Content Understanding. Install 'markitdown[az-content-understanding]' and pass --use-cu --cu-endpoint "<endpoint>". The README notes that every call it routes there is billable too.

For a free, local route, add a text layer to the scan with OCRmyPDF first and then run MarkItDown on the result. Our PDF to Markdown conversion guide walks through that OCR step. To run the OCR in your own script, our Python OCR tutorial covers pytesseract and EasyOCR.

When to Pick PyMuPDF4LLM, Docling or Marker Instead

MarkItDown is light and covers many formats, but it doesn't reconstruct a PDF's layout. When the PDF is the whole job, a layout-aware library usually gives you better Markdown. We ran PyMuPDF4LLM 2.1 on the same support report, and it returned # and ## headings, bold text, a bulleted list and a correct pipe table.

LibraryLicenseHeadings from a PDFTablesScanned pages
MarkItDown 0.1.9MITNoPipe tables on column-aligned pagesVia plugin or Azure (paid)
PyMuPDF4LLM 2.1AGPL-3.0 or Artifex commercialYesYesOCR through an installed engine such as Tesseract
DoclingMITYes, from a layout modelTable structure modelBuilt-in OCR

Watch the license before you ship. PyMuPDF4LLM is AGPL-3.0 unless you buy a commercial license from Artifex. Docling is MIT but brings heavier model dependencies. Marker is another layout-aware option, and our PDF conversion guide covers it. For the MIT-licensed options, our MIT License guide explains the notice you have to ship with them.

We prefer MarkItDown when PDFs are one input among Word files, spreadsheets and HTML in the same pipeline. When a folder of reports is the whole job and headings matter, we'd reach for a layout-aware library first.

Skipping Python for a One-Off PDF

If you need one file converted and don't want a Python environment, use our PDF to Markdown converter. You upload a single PDF and our server extracts its text layer. It uses font size to guess headings and gaps between words to rebuild tables, then loads the Markdown into an editor on the page.

It's not a replacement for MarkItDown in a pipeline. It has no OCR, so scans give little or nothing. It converts one file at a time, with no API or batch mode. Each conversion uses one of the 3 free server operations you get each day, no account needed, and Pro removes that daily cap.

Microsoft PDF to Markdown conversion with MarkItDown takes one pip install and one command, and it's dependable for invoices, forms and LLM ingestion. Just don't expect headings. Budget a cleanup pass for anything people will read, or try a layout-aware library. For a single file, upload it to the PDF to Markdown tool, then fix headings and tables in the editor while you watch the preview.