Marker Tutorial: Fast PDF to Markdown Conversion in Python

Marker is one of the most popular open source tools for turning PDFs into clean Markdown. It was built with one goal in mind: produce accurate, structured output fast, without the heavy per page cost of a full document AI pipeline. If you have a folder of PDFs and you want Markdown that a large language model can actually read, Marker is a strong first choice.

This tutorial walks through installing Marker, converting your first document in Python, batching a whole directory, and tuning the settings that matter. It also covers the honest tradeoffs versus MinerU and PyMuPDF4LLM so you can pick the right tool instead of the loudest one. Everything here is code you can copy, paste, and run today.

What Marker Actually Does

Marker is a Python library that runs a pipeline of deep learning models over a PDF. It detects the layout of each page, orders the reading flow, recognizes text, and reconstructs the document as Markdown. Unlike a plain text extractor, it understands that a page has headings, paragraphs, lists, tables, code blocks, and figures, and it emits Markdown that preserves that structure.

A few things make Marker stand out:

• Speed with GPU: On a modern GPU, Marker processes pages far faster than most vision heavy alternatives, which makes it practical for large batches.
• Clean output: The Markdown is tuned for downstream use in LLM pipelines, with sensible heading levels and preserved tables.
• Formats beyond PDF: Recent versions also handle formats like DOCX, PPTX, and EPUB, so it can be a single entry point for mixed document sets.
• OCR when needed: Marker runs OCR on scanned or image based pages, so it does not fall over on documents that have no embedded text layer.
• Optional LLM boost: You can layer in a language model to improve accuracy on tricky tables and inline math, at the cost of extra time and API calls.

The catch is that Marker is model based, so it wants Python 3.10 or newer, a decent amount of RAM, and ideally a GPU. On CPU only machines it still works, but it is slower. If you just need Markdown from one file without setting up an environment, an online converter like pdftomd.cloud does the same job in your browser in seconds.

Installing Marker

Marker ships on PyPI as marker-pdf. The cleanest approach is a fresh virtual environment so its model dependencies do not collide with the rest of your system.

python -m venv marker-env
source marker-env/bin/activate   # Windows: marker-env\Scripts\activate

pip install marker-pdf

# For non PDF formats (DOCX, PPTX, EPUB, and more)
pip install "marker-pdf[full]"

The first time you run a conversion, Marker downloads its model weights. That download is a one time cost of a few hundred megabytes, so the very first run is slower than every run after it. If you are deploying to a server or a container, warm the cache during the build so production requests are not stuck waiting on a download.

To confirm the install worked, check that the command line entry point is available:

marker_single --help

Your First Conversion in Python

The core of Marker is a converter object that you build once and then call on a file path. Here is the minimal script to turn a single PDF into a Markdown string and write it to disk.

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

# Load the models once. This is the expensive step, so reuse it.
converter = PdfConverter(
    artifact_dict=create_model_dict(),
)

# Run the conversion.
rendered = converter("report.pdf")
markdown, metadata, images = text_from_rendered(rendered)

with open("report.md", "w", encoding="utf-8") as f:
    f.write(markdown)

print(f"Wrote {len(markdown)} characters of Markdown")

A few things worth noting. The create_model_dict() call loads every model Marker needs into memory. It is slow, so build the converter one time and reuse it across many files rather than rebuilding it in a loop. The text_from_rendered helper unpacks the rendered result into the Markdown string, a metadata dictionary, and any extracted images. If your document has figures you want to keep, save those images alongside the Markdown so the links resolve.

Converting from the Command Line

If you do not want to write Python at all, Marker exposes two commands. Use marker_single for one file and marker for a whole folder.

# Convert a single file into an output directory
marker_single report.pdf --output_dir ./out

# Convert every PDF in a folder
marker ./pdfs --output_dir ./out --workers 4

The --workers flag controls how many documents run in parallel. Set it based on your GPU memory: more workers finish a batch faster but each one holds its own copy of the working data. Start with a small number, watch your memory, and increase it until you find the ceiling. For a deeper look at folder wide conversion patterns, see our guide on batch converting PDFs from the command line.

Batch Processing a Directory in Python

The command line is fine for one off jobs, but when you build a pipeline you want control. Here is a script that walks a directory, converts every PDF, and writes matching Markdown files while reusing a single loaded model set.

from pathlib import Path
from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

converter = PdfConverter(artifact_dict=create_model_dict())

source = Path("pdfs")
target = Path("markdown")
target.mkdir(exist_ok=True)

for pdf_path in sorted(source.glob("*.pdf")):
    try:
        rendered = converter(str(pdf_path))
        markdown, _, _ = text_from_rendered(rendered)
        out_path = target / f"{pdf_path.stem}.md"
        out_path.write_text(markdown, encoding="utf-8")
        print(f"Converted {pdf_path.name}")
    except Exception as err:
        print(f"Failed on {pdf_path.name}: {err}")

The try and except block matters more than it looks. In any real batch you will hit a corrupt file, a password protected PDF, or a scan so poor that a model chokes. Without the guard, one bad file kills the whole run. With it, you get a clean log of what failed and a full set of Markdown for everything that worked.

Improving Accuracy with the LLM Option

Marker can call a language model to clean up its output on the hardest parts of a document: merged table cells, inline math, and ambiguous layouts. You enable it by passing a flag and supplying an API key for the provider you want to use.

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.config.parser import ConfigParser

config = {
    "use_llm": True,
    "output_format": "markdown",
}

config_parser = ConfigParser(config)

converter = PdfConverter(
    artifact_dict=create_model_dict(),
    config=config_parser.generate_config_dict(),
    llm_service=config_parser.get_llm_service(),
)

rendered = converter("financial-statement.pdf")

Turning on use_llm noticeably improves tables and equations, which is exactly where most converters struggle. The tradeoff is speed and cost: each page that needs help triggers an API call, so a large batch adds up. A good rule is to run without the LLM by default and only switch it on for documents where table fidelity is critical, such as financial reports or data sheets. If tables are your main pain point, our guide on converting PDF tables to clean Markdown covers the failure modes in depth.

Marker vs MinerU vs PyMuPDF4LLM

These three tools come up together constantly, and they solve overlapping but distinct problems. Here is how they compare on the axes that actually decide your choice.

The short version: reach for PyMuPDF4LLM when your PDFs already have a clean text layer and you want the lightest, fastest option with no GPU. Reach for MinerU when you are processing research papers full of equations and you need the math to survive. Reach for Marker when you want a sensible default that handles mixed real world documents well and scales to big batches on a GPU. Many teams end up using more than one, routing each document to the tool that fits it.

If you want to go deeper on the alternatives, we have full tutorials for PyMuPDF4LLM and MinerU, each with install steps and working code.

When to Use a Hosted Converter Instead

Marker is excellent, but running it well means managing a Python environment, model downloads, GPU memory, and error handling. That is worth it when conversion is a core part of your product or you process thousands of documents a month. It is overkill when you have a handful of PDFs and just need clean Markdown right now.

For those cases, a hosted converter removes all of the setup. PDFtoMD converts your file in the browser, produces clean Markdown with headings, lists, and tables intact, and requires no install. The free tier includes 3 conversions per month with no credit card, which is plenty to test whether the output fits your workflow before you decide to self host. See the use cases page for common ways teams put converted Markdown to work.

Frequently Asked Questions

Does Marker require a GPU?

No, but it strongly benefits from one. Marker runs on CPU only machines and will still produce correct Markdown, it just processes pages more slowly. For a few documents, CPU is fine. For large batches or anything latency sensitive, a GPU makes a dramatic difference.

Can Marker handle scanned PDFs?

Yes. Marker runs OCR on pages that have no embedded text layer, so scanned documents and image based PDFs still convert. Quality depends on the scan: crisp, high resolution scans convert cleanly, while faded or skewed pages may need the LLM option to reach acceptable accuracy.

What Python version does Marker need?

Marker targets Python 3.10 or newer. Use a virtual environment to keep its model dependencies isolated from your other projects, since it pulls in a fairly large set of machine learning packages.

Is Marker free to use?

The core library is open source and free to run on your own hardware. The only cost comes if you enable the optional LLM feature, which makes API calls to a provider you configure and bill for separately. Without that flag, there is no per document cost beyond your own compute.

How does Marker compare to writing a plain PyMuPDF script?

A plain extractor pulls text but loses most structure. Marker reconstructs headings, tables, and reading order using layout models, so the Markdown is genuinely usable downstream. If you only need raw text from simple PDFs, a lighter library is faster. If you need structure, Marker earns its extra weight. For a broader survey of the options, see our overview of converting PDF to Markdown in Python.

The Takeaway

Marker hits a rare sweet spot: fast enough for real batches, accurate enough for production, and open source so you control the pipeline. Install it into a clean virtual environment, build the converter once, reuse it across your files, and turn on the LLM option only where table and math fidelity truly matter. For everything else, the defaults produce clean, LLM ready Markdown out of the box.

If you would rather skip the environment setup entirely, upload your PDF to pdftomd.cloud and get the same clean Markdown in seconds. Whichever path you pick, the goal is the same: stop wrestling with raw PDFs and start working with structured Markdown your tools can actually read.