PDF to Markdown in Python: Text, Tables, Scans

Start with a local text converter for readable PDFs, inspect the result, and add layout analysis or OCR only where the document needs it. The important distinction is between code that writes a Markdown file and a workflow that verifies the required content survived.

This tutorial provides two small Python files: one converts and records the run; the other checks source-page anchors. It keeps conversion errors, empty extraction, and content review separate. For hosted upload, polling, and download code, use the PDF-to-Markdown API guide.

The extraction examples target the versions in our historical October 6, 2026 experiment. The wrapper and validation code were checked locally during this revision, without reinstalling those converters or repeating the PDF/API benchmark. Package-version and deployment considerations are covered in the GitHub project guide.

Decide what the PDF needs

Inspect representative pages before choosing a library:

  • If copied prose matches the visible text and sentence sequence, try native text extraction.
  • If sentences alternate between columns, try layout-aware extraction.
  • If table values survive but labels are split or rotated, review the header-to-value mapping.
  • If a visible page produces no text, configure OCR rather than just changing Markdown formatting.
  • If formulas matter, verify the symbols and grouping separately from ordinary prose.

A mixed document can need more than one of these treatments. A successful opening page does not establish that its scanned appendix was processed.

1. Create an isolated environment

Use Python 3.11 for the examples. The historical test used Python 3.11.14. These pins reproduce the intended API generation, not a recommendation to treat an old version as the latest release.

python3.11 -m venv .venv
        source .venv/bin/activate
        python -m pip install "markitdown[pdf]==0.1.8"
        

On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell instead of the source command.

For the historical PyMuPDF4LLM alternative, use a separate environment and install:

python -m pip install "pymupdf4llm==1.28.2" "pymupdf==1.28.2"
        

The commands pin the main packages, not every transitive dependency. Save a dependency lock or installed-package inventory for an environment you intend to reproduce.

Version note, checked October 19, 2026: the PyMuPDF4LLM repository now describes a compatibility package after the functionality moved into PyMuPDF 2.x. The historical import pymupdf4llm example below belongs to the tested 1.28.2 environment. Do not silently combine it with a 2.x installation or claim these results evaluate the newer API. Review current migration and licensing requirements before choosing a production version.

MarkItDown's official README documents format-specific extras. This tutorial disables plugins and uses a local file path; it does not evaluate optional cloud or OCR integrations.

2. Convert one file and preserve a run record

Save this as convert_local.py:

import argparse
        import hashlib
        import importlib.metadata
        import json
        import sys
        import time
        from pathlib import Path


        def extract(source, engine):
            if engine == "markitdown":
                from markitdown import MarkItDown
                return MarkItDown(enable_plugins=False).convert_local(str(source)).markdown
            import pymupdf4llm
            return pymupdf4llm.to_markdown(str(source))


        def main():
            parser = argparse.ArgumentParser()
            parser.add_argument("source", type=Path)
            parser.add_argument("output_dir", type=Path)
            parser.add_argument("--engine", choices=["markitdown", "pymupdf4llm"],
                                default="markitdown")
            args = parser.parse_args()
            if not args.source.is_file():
                parser.error(f"Input file not found: {args.source}")
            # A separate run directory prevents old output from looking like new output.
            args.output_dir.mkdir(parents=True, exist_ok=False)
            record = {"source_name": args.source.name,
                      "source_sha256": hashlib.sha256(args.source.read_bytes()).hexdigest(),
                      "engine": args.engine, "review_status": "not_reviewed"}
            start = time.monotonic()
            exit_code = 0
            try:
                record["package_version"] = importlib.metadata.version(args.engine)
                markdown = extract(args.source, args.engine)
                (args.output_dir / "raw.md").write_text(markdown, encoding="utf-8")
                record["status"] = "extracted" if markdown.strip() else "empty_extraction"
                if not markdown.strip():
                    exit_code = 2
                    print("No text recovered. Inspect the source and OCR configuration.", file=sys.stderr)
            except Exception as exc:
                record["status"] = "failed"
                record["error"] = f"{type(exc).__name__}: {exc}"
                print(record["error"], file=sys.stderr)
                exit_code = 1
            finally:
                record["elapsed_seconds"] = round(time.monotonic() - start, 4)
                (args.output_dir / "run.json").write_text(json.dumps(record, indent=2),
                                                         encoding="utf-8")
            return exit_code


        if __name__ == "__main__":
            raise SystemExit(main())
        

Run one engine at a time, with a new output directory:

python convert_local.py input.pdf runs/text --engine markitdown
        python convert_local.py input.pdf runs/layout --engine pymupdf4llm
        

A completed extraction writes raw.md; run.json records the outcome when possible. The record includes the source hash, selected package version, status, and elapsed time. Status extracted means nonempty text was returned; review_status deliberately remains not_reviewed.

Exit codes are:

  • 0: nonempty output was written, but content still needs review.
  • 1: extraction or writing raised an error, recorded in run.json when possible.
  • 2: extraction returned no text, or the command-line arguments were invalid.

An empty output is a diagnostic result, not a reason to keep rerunning the same extraction call. Inspect the source for image-only pages, damaged text layers, encryption, or unsupported content. A nonempty output can also be incomplete.

The script refuses an existing output directory to avoid confusing old results with a new run. It does not implement a batch queue, OCR fallback, automatic table repair, or a security sandbox for untrusted uploads. If you turn it into a service, add input validation, resource limits, isolation, and access controls separately.

3. Check required page content

A simple anchor check can catch a scanned page missing from otherwise readable output. Choose distinctive phrases from the actual source, including required first, middle, and final pages. Keep those expectations separate from the generated text.

For the historical mixed-document fixture, this expected.json checks the scanned third page:

[
          {
            "page": 3,
            "anchor": "This page exists only as a picture."
          }
        ]
        

This anchor belongs to that fixture. Replace it with source-verified phrases for your own PDF, and include every page whose coverage matters. Do not generate the expected phrases from the conversion you are trying to validate.

Save this as check_coverage.py:

import json
        import re
        import sys
        from pathlib import Path


        def normalize(text):
            return re.sub(r"\s+", " ", text).strip().casefold()


        def check(markdown, expected):
            if not expected:
                raise ValueError("Provide at least one source-verified anchor.")
            text = normalize(markdown)
            results = []
            for item in expected:
                anchor = normalize(item["anchor"])
                if not anchor:
                    raise ValueError("An empty anchor cannot verify page coverage.")
                results.append({"page": item["page"], "anchor": item["anchor"],
                                "found": anchor in text})
            return results


        if __name__ == "__main__":
            if len(sys.argv) != 3:
                raise SystemExit("Usage: python check_coverage.py raw.md expected.json")
            markdown = Path(sys.argv[1]).read_text(encoding="utf-8")
            expected = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
            results = check(markdown, expected)
            print(json.dumps(results, indent=2))
            raise SystemExit(0 if all(item["found"] for item in results) else 2)
        

Run it separately from extraction:

python check_coverage.py runs/text/raw.md expected.json
        

It returns exit code 2 if a required anchor is absent. It normalizes case and whitespace only. A split word, inserted formatting, or OCR spelling error may require inspection rather than proving the entire page is absent. Conversely, a repeated phrase can create a false positive, so choose distinctive anchors.

Passing this check does not validate table relationships, complete reading order, or every word on a page. It is a small coverage gate, not an accuracy score or an automatic approval to use the document for every purpose.

4. Inspect columns and tables before cleanup

In the historical two-column fixture, MarkItDown returned this unedited sequence:

Invoice reconciliation starts with the export file, not

        Demand forecasts fail upward more often than they

        the ledger. Teams that reconcile weekly pull the

        fail downward. Optimistic sales inputs push safety
        

The output splices together different subjects. A line-break cleanup would preserve the wrong order. The tested PyMuPDF4LLM call kept complete sentences in the intended sequence on this fixture. Raw MarkItDown column output.

The historical pdfplumber.extract_text() baseline also interleaved those columns. That result applies to the raw-text call we tested, not all of pdfplumber's layout and table APIs. Use pdfplumber when you need low-level extraction and debugging controls, rather than assuming its text output is already a Markdown table. pdfplumber documentation.

Tables need a different check. Trace each value to its row label, leaf column heading, and any parent heading. In the grouped-price fixture, the local converters retained rows while splitting parent and leaf labels. In the rotated-header fixture, labels were displaced or reversed; a first data row could occupy Markdown's header position.

For a source table with a parent heading “Price” over “Unit” and “Total,” a reviewed flat schema can use Price / Unit and Price / Total. Preserve the raw table beside this transformation. Do not assume every visually similar table has the same column mapping.

If the destination accepts HTML, retain complex table structure when that is more faithful than flattening it. If the destination requires pipe tables, make the normalization explicit and verify that it has not dropped group labels, units, or footnotes.

5. Add OCR only as a configured route

The historical MarkItDown run had plugins disabled. The tested PyMuPDF4LLM default environment had no usable OCR path for the scan. Neither recovered the image-only fixture's text. This does not establish that every configuration of those libraries lacks OCR.

For a local OCR route, verify the engine, language data, model files, and runtime dependencies before testing. Marker is one documented option, but it was not run in this experiment. Its current code, model licensing, and deployment requirements need separate review. The repository-selection guide explains those boundaries without presenting an unexecuted configuration as a result.

If remote processing is appropriate, Markovo's cached October 6 jobs recovered the scan sentence and all three mixed-document page anchors. Its tables were HTML, not pipe-table Markdown. Its formula result was weaker than the native text paths on the linear-expression fixture.

The unedited formula output included:

$$
        \[a^{\wedge}2+b^{\wedge}2=c^{\wedge}2\]
        $$
        

Nested display delimiters and damaged superscript notation require source review. Renderer support alone cannot correct a transcription error. Saved equation response.

For a hosted Python integration with an explicit Credit ceiling and resumable state, follow the upload → confirm → poll → download example. Keep API credentials in the server environment. That workflow requires network access and an account; it is not an offline converter.

6. Keep cleanup and acceptance separate

After the raw result passes the relevant checks, write any normalization into a separate file, such as reviewed.md. Record what changed and why.

Useful changes include reconstructing a verified table header or removing repeated page furniture. Risky changes include asking an LLM to invent a missing sentence, guess an amount's column, or repair a formula without the source region.

For downstream search or RAG, attach source ID, revision, page, and block information to the accepted text. If the converter does not provide page-level metadata, retain that limitation instead of inventing citations. The LLM ingestion guide provides a separate runnable chunking example with accepted and held blocks.

Historical results that explain these checks

The source experiment ran on October 6, 2026, with Python 3.11.14, MarkItDown 0.1.8, PyMuPDF4LLM 1.28.2, and pdfplumber 0.11.10. It used eight generated English PDFs with paired reference data. Markovo results came from cached API jobs created that day. These same fixtures and cached outputs appear in related guides; they are not independent replications.

Fixture or check MarkItDown PyMuPDF4LLM pdfplumber text baseline Cached Markovo
Two-column sentence-match recall 0.1111 1.0 0.1111 1.0
Mixed-document page-anchor coverage 2/3 2/3 2/3 3/3
Scan sentence-match recall 0.0 0.0 0.0 1.0
Linear-formula normalized expression recall 1.0 0.75 1.0 0.5

Both Markdown libraries retained the simple table as pipe syntax in this experiment. Their grouped and rotated header checks failed even though row-string checks passed. Markovo retained the tested leaf-header strings but used HTML; a same-line score does not establish merged-header semantics. The pdfplumber call retained text without creating a Markdown table.

Markovo is the service we build. Its formula and output-format limits remain part of the evidence. A service-reported quality_score is not independent validation. The saved records also contain preflight billing counts and post-conversion OCR counts; those fields do not establish how each table or expression was recovered.

Read the full score matrix and metric definitions, local execution records, and cached API provenance for the remaining fixtures. The empty pdfplumber scan output is preserved rather than replaced with a success example.

These scores are normalized string and anchor checks, not production accuracy, mathematical equivalence, OCR confidence, or LLM answer quality. The formula fixture contains linear text expressions, not a comprehensive test of fractions, matrices, or handwriting. Cached elapsed_s=0.0 values are not conversion timings.

What was verified for this revision

The new wrapper and coverage checker were syntax-checked and exercised with local stubs and illustrative text. The checks covered successful output, empty extraction, extraction failure, source-anchor presence, and missing anchors. The historical converter versions were not reinstalled or rerun, and no new authenticated Markovo conversion was submitted.

That boundary matters: the code gives you a practical starting point, while your own documents determine whether a route is suitable. Start with a small representative sample, preserve the raw files, and accept only the content relationships your application actually needs.

Sources

  1. PyMuPDF4LLM repository
  2. official README
  3. Raw MarkItDown column output
  4. pdfplumber documentation
  5. Saved equation response
  6. full score matrix and metric definitions
  7. local execution records
  8. cached API provenance
  9. pdfplumber scan output