Marker pdf

marker-pdf

Drive the marker CLI to turn documents into clean Markdown/JSON/HTML. Marker preserves tables, headings, reading order, and equations, and OCRs scanned pages.

Preflight (detect, don't ask)

Before anything else, check whether marker is already installed:

which marker_single

• Found → it's installed. Proceed straight to the decision flow. Do not show the user install steps or ask them to set anything up.
• Not found → install it once (see Install / repair), then proceed.

Adapt silently from what you detect — don't open with a menu of questions. Only ask the user when a choice genuinely can't be inferred and is costly to get wrong (e.g. a very large job where max-quality --use_llm vs speed matters). Output location, OCR, and format are all inferable — pick a sensible default and state it.

Decision flow (read this first)

1. Always verify on a small page range before a full run. First convert ~2 pages with --page_range 0-1, eyeball the output, then run the whole file. This catches OCR/layout problems before a long job.
2. OCR on or off? Born-digital PDF with selectable text → add --disable_ocr (much faster). Scanned/photographed pages or garbled text → leave OCR on (default).
3. Output format? Notes / LLM input → markdown (default). Pipeline / need bounding boxes & structure → json. RAG ingestion → chunks. Web display → html.
4. Quality not good enough? Escalate to LLM mode (--use_llm). Better tables, merged cells, equations, and form handling — at the cost of latency and API spend. See REFERENCE.md.

Quick start

# One file → markdown in ./out (verify on 2 pages first)
marker_single input.pdf --page_range 0-1 --output_dir ./out   # check this
marker_single input.pdf --output_dir ./out                    # then full run

# A whole folder of PDFs
marker ./pdfs --output_dir ./markdown

Output lands in <output_dir>/<filename>/: the .md file, a _meta.json sidecar (page stats, detected languages, block counts), and any extracted images. --page_range is zero-indexed and accepts lists/ranges: 0,5-10,20.

Common recipes

# Born-digital PDF, skip OCR for speed
marker_single report.pdf --disable_ocr --output_dir ./out

# Structured JSON instead of markdown
marker_single report.pdf --output_format json --output_dir ./out

# Text only, don't extract images
marker_single report.pdf --disable_image_extraction --output_dir ./out

# Higher-accuracy pass via an LLM (see REFERENCE.md for provider setup)
marker_single report.pdf --use_llm --output_dir ./out

The CLI tools

Command	Use
marker_single	Convert one file (primary tool)
marker	Convert a folder
marker_gui	Browser UI (Streamlit) — easiest for non-CLI users
marker_server	Run as a local API
marker_chunk_convert	Split a huge batch across workers
marker_extract	LLM-driven structured extraction

First-run / "it's slow" / "it's broken"

• First conversion downloads several hundred MB of models and produces no output for a while. This is normal — it's a one-time cache, fast afterwards. Don't kill it.
• Expect it to be slow on dense docs. Locally, plan for roughly 1–2 min per page on text/table/equation-heavy PDFs (a clean 2-page sample badly under-predicts a 20-page paper). Set this expectation with the user up front; for big jobs, run in the background and check back, or use marker_gui/marker_server. Output is only written at the very end, so an absent output folder ≠ no progress.
• Don't pipe a long run through tail / head — they buffer until the process exits, hiding all progress until it's done. To monitor a long job, run in the background and stream output to a log: marker_single … --output_dir ./out > /tmp/marker.log 2>&1 &, then watch tail -f /tmp/marker.log.
• Running two conversions at once shares one GPU and the model download — both crawl. Run them one at a time.
• marker_single: command not found → ~/.local/bin isn't on PATH, or it isn't installed. See install below.
• TypeError: unsupported operand type(s) for | on import → marker is running on Python ≤3.9. It needs 3.10+. Reinstall (below).
• Full flag reference, LLM-mode provider setup, and deeper troubleshooting: REFERENCE.md.

Install / repair (only if preflight fails)

Skip this entirely if which marker_single already resolved. Otherwise: marker needs Python 3.10+. Install it as an isolated CLI tool (recommended over bare pip, which picks the system Python and silently breaks on 3.9):

uv tool install --python 3.12 marker-pdf

This installs all six commands into ~/.local/bin. To repair a broken older install, remove it first (pip uninstall -y marker-pdf) then run the command above.