Convert PDF to Markdown in Python: A Practical Guide

Choose a Python PDF to Markdown approach

Choose around the PDF layouts and file types you actually have. For PDF-focused Python work, PyMuPDF4LLM is a practical first package to evaluate: it can return Markdown, JSON, or text, and offers layout, page-chunk, OCR, and image options. If your input queue also includes Word, PowerPoint, Excel, and other formats, compare Microsoft's MarkItDown project. Its maintainers describe it as an LLM-oriented converter and caution that the output may not suit high-fidelity human conversion. A browser converter is simpler for an occasional file; a hosted API fits a backend workflow but adds file-transfer and service controls. Compare representative documents before choosing.

Convert one PDF to Markdown with Python

PyMuPDF4LLM provides a direct to_markdown() call. The method returns Markdown text, so a small script can decide where the output goes and how to name it. Install the package in the environment that will run the script, then begin with one representative PDF rather than a whole archive. The basic example below uses the package name and method shown in the project documentation.

import pymupdf4llm
from pathlib import Path

source = Path("report.pdf")
markdown = pymupdf4llm.to_markdown(str(source))
output = source.with_suffix(".md")
output.write_text(markdown, encoding="utf-8")

print("Saved", output)

Install the library and save the Markdown file

Use an isolated virtual environment when the conversion script is part of a project, so its PDF dependencies do not unexpectedly affect other Python work. The documented package install command is pip install pymupdf4llm. Once installed, the example writes beside the source PDF and explicitly uses UTF-8, which avoids relying on the machine’s default text encoding. If your application accepts files from users, validate the extension and size before parsing, choose an output directory deliberately, and avoid placing generated files in a public web directory by accident.

A useful first run is intentionally small: convert one file, open the .md output in a plain-text editor, and compare it with the PDF. This tells you whether the library’s defaults are suitable before you build a batch job around them. The exact package options can change, so check the current official API reference before depending on optional arguments in a long-lived pipeline.

Handle scanned PDFs and OCR deliberately

PyMuPDF4LLM checks pages and uses OCR automatically when it detects that recognition is needed. The official documentation checked on 2026-10-02 describes Tesseract and RapidOCR adapters. Make sure an OCR engine is available in the same environment that runs Python; Tesseract also needs the language data for the document. If a scan returns little text, first check the installed package version, engine, and language data. Use force_ocr=True only when the native text layer is corrupt or automatic detection missed a page: it bypasses the normal check and forces OCR, which can slow clean digital pages and reduce their quality. Review names, identifiers, totals, and mixed-language text against the scan.

import pymupdf4llm

# OCR runs automatically when the installed engine detects that a page needs it.
markdown = pymupdf4llm.to_markdown("scanned-report.pdf")

# With Tesseract, choose language data installed in the environment.
markdown = pymupdf4llm.to_markdown(
    "scanned-report.pdf",
    ocr_language="eng+chi_sim",
)

Process multiple PDFs with predictable paths

Batch conversion is mostly a file-management problem. Keep source files separate from output files, create the destination folder before the loop, and derive each Markdown filename from the PDF stem. Catch errors per file so one damaged or password-protected PDF does not silently stop the entire folder. Record failures in a log that an operator can inspect; do not silently mark the batch as complete. For large jobs, add bounded concurrency only after measuring memory use and the converter’s documented behavior.

The example below handles the top level of one input folder. If documents are nested, use rglob("*.pdf") and preserve relative paths so two files named report.pdf do not overwrite each other. If conversion is a recurring backend workload rather than a local script, compare this approach with a job-based API and its authentication, retry, and retention model.

from pathlib import Path
import logging
import pymupdf4llm

source_dir = Path("pdfs")
output_dir = Path("markdown")
output_dir.mkdir(parents=True, exist_ok=True)
logging.basicConfig(
    filename=output_dir / "conversion.log",
    level=logging.ERROR,
    format="%(asctime)s %(levelname)s %(message)s",
)

for pdf_path in sorted(source_dir.glob("*.pdf")):
    try:
        markdown = pymupdf4llm.to_markdown(str(pdf_path))
        target = output_dir / (pdf_path.stem + ".md")
        target.write_text(markdown, encoding="utf-8")
    except Exception:
        logging.exception("Could not convert %s", pdf_path.name)

Keep images and tables useful in Markdown

Plain Markdown can represent headings, lists, links, and many simple tables. More complex tables, charts, equations, and page artwork may need a different representation or a separate image asset. If your output depends on extracted images, review the current documented options for write_images, image paths, and formats; keep those files alongside the Markdown and verify that generated references resolve from the place where the .md file will be read. Do not assume that every figure can be converted into descriptive text or that visual layout survives as-is.

For a knowledge base, preserve enough context for a reader to trace an important passage back to its source page. Page-separated output or metadata may be useful, but choose based on the retriever and citation behavior you need. For a browser-based workflow focused on exported images and tables, see the PDF to Markdown images and tables guide. The existing PDF to Markdown for RAG guide covers chunking and retrieval preparation; this tutorial stays focused on the Python extraction step.

markdown = pymupdf4llm.to_markdown(
    "report.pdf",
    write_images=True,
    image_path="output_assets",
    image_format="png",
)

Diagnose common Python PDF to Markdown failures

If Python cannot import the package, first check which interpreter runs the script. Run python -m pip show pymupdf4llm from that same environment; a notebook, terminal, or scheduled job may use a different interpreter. A FileNotFoundError often means a relative path is being resolved from an unexpected working directory. Print source.resolve() while debugging or test with an absolute path.

If a scanned PDF produces little text, confirm that an OCR engine and the needed language data are installed in the environment. Keep force_ocr=True for pages whose text layer is missing or unreliable; clean digital pages usually do not need forced OCR. When the Markdown points to missing images, keep the exported asset directory with the .md file and check the relative paths.

For a batch job, record a success or failure for every input and save the exception details to a log. A generated file only proves that the parser returned something. It does not prove that every page, table, or recognized value is correct.

Review the Markdown before you rely on it

A successful function call only means the parser returned output. It does not prove that the document’s structure was reconstructed correctly. Before indexing, publishing, or extracting business facts, compare a few pages against the source PDF. Include an opening page, a page with columns, a table page, a page with footnotes or repeated headers, and a scanned page if your corpus contains scans. Fix the extraction configuration or route difficult files to another method when the output fails your requirements.

Know what a PDF to Markdown converter cannot guarantee

PDF records where content is drawn on a page; it does not always contain the semantic structure that Markdown needs. A two-column paper, a form, an engineering drawing, and a clean text report are different extraction problems. Layout-aware software can make useful guesses, but output should be judged against the pages and the downstream task. If the document contains tables, formulas, or diagrams that must remain exact, keep the source PDF and use page references or separate assets alongside the Markdown.

Processing locally can keep the file inside the environment you control, but security also depends on dependencies, storage paths, logs, backups, and process isolation. Microsoft's MarkItDown documentation notes that conversion runs with the current process's access; isolate jobs and narrow file access when processing untrusted documents. The PyMuPDF4LLM repository declares AGPL-3.0; review the current license and dependency terms before distributing a product that uses it. A hosted API may reduce the work of managing a parser while requiring you to review upload and retention terms. For a managed workflow, see the PDF to Markdown API guide; for a quick selectable-text preview, return to the online PDF to Markdown converter.

PDF to Markdown Python questions

A reliable starting workflow

For a local script, install the documented package, convert one file, write the result as UTF-8, and compare it with the source. Add OCR, batch handling, and image extraction only when the document set needs them. Keep failed-file logs, and check output before using it for search or decisions. If you do not need a repeatable Python workflow, use the browser PDF to Markdown converter; for managed jobs, see the PDF conversion API guide.