Turn PDFs Into Text Your AI Can Read With MarkItDown

MarkItDown is a free tool from Microsoft that turns PDFs, Word files, and PowerPoints into Markdown. You run one command, open the result, and give your AI agent a clean text file instead of a messy PDF.

What this helps you do

AI agents such as Claude Code often struggle with PDFs. Text comes out in the wrong order, tables fall apart, or the agent misses a whole section. Converting the file first fixes the input:

• You get one .md file with the headings, lists, tables, and links kept as plain text.
• You can open that file and see exactly what your agent will read.
• Your agent can search, quote, and edit it like any other text file.

MarkItDown also handles spreadsheets, web pages, CSV and JSON files, EPUB books, and ZIP folders. Scanned PDFs need one extra step, covered below.

Before you start

• Python 3.10 to 3.14. Check in Terminal (Mac) or Command Prompt (Windows) with python3 --version. On Windows, try python --version.
• A terminal. Terminal on Mac, Command Prompt or PowerShell on Windows.
• One PDF to test, saved in a folder you can find, such as a manual, a report, or a course handout.
• An AI agent that reads files, such as Claude Code. New to Claude Code? Start with the Claude setup checklist.

MarkItDown is free and open source under the MIT license. Normal conversion runs on your computer.

Terms to know

• Markdown: plain text with light formatting marks. A # starts a heading and a - starts a list item. AI models read it well.
• .md file: a file saved in Markdown. Any text editor opens it.
• Virtual environment: a private folder for Python tools, so installing one tool does not break another.
• Scanned PDF: a PDF made from photos or scans of pages. Each page is a picture of text, not real text.
• OCR (optical character recognition): reading text out of an image.
• Plugin: an optional add-on that gives MarkItDown a new ability.

Step-by-step

1. Open your terminal in your PDF's folder. On a Mac, type cd (with a space), drag the folder into Terminal, and press Enter.

2. Create and turn on a virtual environment. Run these two lines:

   python3 -m venv .venv
   source .venv/bin/activate

   On Windows, use python -m venv .venv, then .venv\Scripts\activate. You should see (.venv) at the start of your terminal line.

3. Install MarkItDown. Run pip install 'markitdown[all]'. The [all] part adds support for every file type. On Windows, use double quotes instead of single quotes.

4. Convert your PDF. Run the command in the Copy this section with your file names. When it finishes, a new .md file appears in the folder.

5. Open the Markdown file yourself. Open it in any text editor. Check that the headings, steps, and tables you care about came out. If the file is empty or nearly empty, you probably have a scanned PDF. Jump to "Scanned PDFs" below.

6. Give it to your agent. In Claude Code, paste the prompt from the Copy this section. Because you already checked the text, you know the agent is working from the right content.

Next time you open a new terminal, run source .venv/bin/activate in that folder again before using markitdown.

Scanned PDFs

A scanned page is a picture of text, so the normal conversion finds nothing to pull out. MarkItDown's optional OCR plugin fixes this by sending each page image to an AI model that reads it.

1. Install the plugin and a client for the model: pip install markitdown-ocr openai

2. Get an API key from OpenAI or another OpenAI-compatible provider, and set it in your terminal: export OPENAI_API_KEY="your-key"

3. Save this as ocr.py in the same folder:

   import sys
   from markitdown import MarkItDown
   from openai import OpenAI
   
   md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o")
   result = md.convert(sys.argv[1])
   open(sys.argv[2], "w", encoding="utf-8").write(result.markdown)

4. Run python3 ocr.py scanned.pdf scanned.md. OCR text shows up in the file between *[Image OCR] and [End OCR]* markers.

If your account does not offer the model named in the script, swap in another model that accepts images. Check the plugin's official instructions for the current details.

Copy this

The convert command. Run this in your terminal. Replace the bracketed names with your file names.

markitdown [YOUR-FILE].pdf -o [YOUR-FILE].md

The prompt for your agent. Paste this into Claude Code after the conversion. Replace the bracketed parts.

Read [YOUR-FILE].md and make me a checklist of the steps in [SECTION NAME OR NUMBER]. Use only what is in the file. Quote the heading each step comes from, and tell me if any step looks cut off or out of order.

Things to know

• The command works the same for Word and PowerPoint. Swap in your .docx or .pptx file name.

• Convert a whole folder at once on Mac or Linux. Run this in the folder, and every PDF gets its own .md file:

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

• OCR costs money and sends pages out. Normal conversion stays on your computer and is free. The OCR plugin sends page images to the model provider you choose, and each call is billed by that provider. Do not use it on documents you are not allowed to share.

• If no model is set, OCR is skipped without an error. The plugin falls back to normal conversion, so a scanned PDF still comes out empty.

• The output is built for AI, not for print. It keeps structure and text. It does not keep page layout, fonts, or exact formatting.

• Check before you trust. Always open the .md file and skim it. If you can read it, so can your agent.

Want to go further with a PDF? See how to turn a PDF into a clickable visual guide with Claude.

If something goes wrong

• command not found: markitdown: your virtual environment is off. Run source .venv/bin/activate (Mac) or .venv\Scripts\activate (Windows) in the folder where you created it.
• externally-managed-environment error during install: you skipped the virtual environment. Do step 2, then install again.
• The .md file is empty or has only a few lines: the PDF is probably scanned. Use the OCR steps above.
• OCR text is missing after running ocr.py: check that your API key is set in the same terminal window and that the model accepts images.
• Tables look messy: open the original next to the Markdown and fix the table by hand, or ask your agent to rebuild that one table from the PDF page you name.

Final check

Pass if you can open your new .md file, read the section you care about in the right order, and your agent's checklist matches that section without adding steps.