Turning PDFs Into Markdown Without Losing Your Mind
You've got a PDF full of tables, formulas, and diagrams that you need in Markdown. Copy-pasting gives you a mess of broken formatting. OCR tools choke on anything that isn't plain text. So what do you reach for? MarkPDFDown is a tool that uses multimodal large language models to transcribe PDFs (and images) into clean, editable Markdown.
What It Does
MarkPDFDown takes a PDF or an image file and converts it into Markdown, using multimodal LLMs to interpret the document's contents. It routes model calls through LiteLLM, which means it can talk to both OpenAI and OpenRouter without you rewriting anything. The project also ships a desktop app if you'd rather click buttons than type commands.
Under the hood, it's a Python package with a modular architecture—the README calls out a clean separation of concerns, which matters if you plan to poke at the internals or extend it. You can install it with uv or conda, configure it through environment variables, and run it either as a CLI tool or as a Python module. There's also a pipe mode designed to play nicely with Docker.
The feature list is short but covers the practical stuff: PDF to Markdown, image to Markdown, page range selection, and format preservation for headings, lists, and tables.
Why It's Cool
It handles the documents other tools give up on. The README specifically mentions tables, formulas, and diagrams. Those are exactly the elements that break naive text extraction—a formula comes out as garbled symbols, a table loses its structure entirely. Using a multimodal model means the tool can actually look at the page rather than just scraping a text layer.
Provider flexibility through LiteLLM. You're not locked into one vendor. The README lists OpenAI models like gpt-4o and gpt-4o-mini, plus OpenRouter options including Claude 3.5 Sonnet, Gemini Pro Vision, and Llama 3.2 90B Vision. Swapping models is a one-line change in your .env file. That's a smart abstraction—model capabilities and pricing shift constantly, and you don't want to be stuck when they do.
Two usage modes that fit different workflows. File mode is the recommended path: markpdfdown --input document.pdf --output output.md. But the pipe mode (markpdfdown < document.pdf > output.md) is genuinely useful for scripting and containerized environments. Plenty of CLI tools only support one or the other.
Page range selection. If you're working with a 400-page report and only need chapter three, you can specify --start 5 --end 15 and skip the rest. That saves both time and API tokens—which, if you're paying per token, is real money.
A desktop app for the command-line-averse. Running npx -y markpdfdown gets you a GUI. It's a separate repository, but it's a nice acknowledgment that not everyone wants to live in a terminal.
Sensible configuration defaults. TEMPERATURE=0.3, MAX_TOKENS=8192, RETRY_TIMES=3. The temperature setting is low, which makes sense for a transcription task—you want accuracy, not creativity. And retry logic is built in, because API calls fail sometimes.
How to Try It
The README recommends uv for installation. Here's the full path:
- Install uv if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh
- Clone and set up:
git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown
uv sync
uv pip install -e .
- Configure your environment. Copy the sample file and edit it:
cp .env.sample .env
Set your model and API key:
MODEL_NAME=gpt-4o
OPENAI_API_KEY=your-openai-api-key
- Convert something:
markpdfdown --input document.pdf --output output.md
Or if you want the desktop app instead:
npx -y markpdfdown
The repository is at github.com/MarkPDFdown/markpdfdown, and the desktop app lives at github.com/MarkPDFdown/markpdfdown-desktop.
Final Thoughts
MarkPDFDown is a focused tool that does one thing: get your PDF content into Markdown without wrecking the structure. It leans on multimodal models to handle the hard cases—tables, formulas, diagrams—and gives you model choice through LiteLLM so you're not betting on a single provider. If you regularly deal with PDFs that need to become documentation, notes, or version-controlled text, it's worth a look. The setup is straightforward, the configuration is minimal, and the pipe mode means it can slot into existing scripts without much fuss. Just keep in mind you'll need API access to one of the supported providers, and larger documents will cost you tokens.