PDF to Markdown on GitHub: Choose by PDF Type

Choose a PDF-to-Markdown project by the documents you need to read and the deployment you can support. Selectable prose, multi-column pages, grouped tables, scans, and formulas put different demands on a converter. A familiar repository name or a large star count does not establish that the output is suitable for your application.

This guide separates two kinds of evidence:

  • Repository, license, and deployment documentation checked on October 19, 2026.
  • Historical synthetic-PDF results recorded on October 6, 2026, using specific installed versions.

The documentation review is current to that check date. It does not turn the historical results into a test of today's default branches or newest packages.

Start with a shortlist by PDF type

Your main requirement Project to evaluate What still needs checking
Local conversion of selectable prose and simple tables MarkItDown Column order, special table headers, and missing scanned pages
Layout-aware native PDF extraction PyMuPDF / the historical PyMuPDF4LLM interface API generation, licensing, table semantics, and OCR setup
Model-based document reconstruction and OCR Marker Model licensing, inference backend, resource use, and actual output quality
Detailed text/table extraction and PDF debugging pdfplumber Your own Markdown rendering and any separate OCR route

A document may cross several rows. In our historical mixed fixture, native text and tables survived the local calls while the scanned appendix disappeared. Check the full set of required pages, not only a readable first page.

If you need a runnable local starting point, the Python tutorial supplies separate conversion and coverage-checking scripts. The rest of this guide focuses on choosing and deploying the project behind those calls.

Verify the repository and package identity

These are the official project repositories reviewed for this guide. A wrapper or fork with a similar name may add different dependencies, services, or licensing obligations.

Project Verified repository Package or interface to distinguish
MarkItDown microsoft/markitdown markitdown, with format-specific extras
PyMuPDF4LLM pymupdf/pymupdf4llm Historical pymupdf4llm API; see the migration note below
PyMuPDF pymupdf/PyMuPDF Current core project and the documented 2.x destination for 4llm functionality
Marker datalab-to/marker Python package marker-pdf, not an unrelated package named marker
pdfplumber jsvine/pdfplumber pdfplumber; text/table primitives rather than a turnkey Markdown conversion service

Before installing a fork, trace its conversion command to the actual implementation. Check whether it processes files locally or forwards them to a service. A desktop interface, Docker image, or REST wrapper does not by itself change those properties.

PyMuPDF4LLM has a version transition to account for

At the October 19 review, the PyMuPDF4LLM main README described an empty compatibility package after the former 4llm code moved into PyMuPDF 2.x. The official documentation covering the 1.28.2 generation still showed the pymupdf4llm installation and import path. Repository migration notice, 1.28.2-generation documentation.

Our October 6 results used PyMuPDF4LLM 1.28.2. Reproduce them in that API generation, or evaluate the newer generation as a separate test. Do not combine an old code snippet, a new unpinned package, and historical scores as if they described one configuration.

Licensing belongs in the first deployment review

A code license and a model-weight license can be different. The repository license badge is a useful starting point, not a complete review of every dependency and deployment condition.

Project Code-license documentation Deployment question
MarkItDown MIT Which optional dependencies or cloud services will your selected path use?
PyMuPDF4LLM / PyMuPDF stack AGPL-3.0 repository license; Artifex also documents commercial licensing Which license covers your distribution or service deployment?
Marker Apache-2.0 code license, with separate model terms Does the intended use satisfy the model-weight license as well as the code license?
pdfplumber MIT What additional OCR, rendering, and service components are you adding?

PyMuPDF's official license explanation describes open-source and commercial options. Do not label the stack as MIT or assume that every proprietary use is automatically covered by a permissive license.

Marker's current model license has conditions involving revenue, funding, and competing products or services. The US$5 million thresholds do not reduce the whole license to “free below $5 million”; the competition restriction is separate, and exceptions have their own scope. A conversion product evaluating integration should review the complete terms for its specific use.

These are documented licensing distinctions, not a legal determination about your application. Record the exact release and applicable license files during evaluation rather than relying indefinitely on a changing default branch.

Understand the runtime and offline boundary

MarkItDown: a local library with optional network paths

MarkItDown supplies a Python library and CLI. Its README documents format-specific extras, an all-formats install, and Docker. Built-in local-file conversion can run locally, while Azure integrations, configured LLM features, and remote URL inputs are separate paths with different network requirements. Official README.

For an untrusted-upload service, validate paths and destinations and use narrowly scoped file or stream APIs. Our historical experiment used convert_local() with plugins disabled. It did not evaluate every optional OCR or cloud integration.

PyMuPDF: local processing still needs the correct components

The current PyMuPDF project describes in-process local execution and air-gapped deployment after installation. OCR through Tesseract requires the relevant engine and language resources to be installed separately. PyMuPDF repository, installation and OCR dependencies.

Our default 1.28.2 configuration did not recover the scan fixture. That is evidence about the tested environment, not proof that the library cannot perform OCR when configured appropriately.

Marker: provision the inference stack, not just the Python package

Marker's current README documents Python and PyTorch requirements and local inference backends, including vLLM on NVIDIA systems and llama.cpp on other supported systems. Optional LLM modes can use cloud services; a local service such as Ollama has a different data flow. Official README.

Before claiming offline operation, provision dependencies and model weights, select local endpoints, and test with outbound network access disabled. Check cold-start behavior and model storage as well as steady-state conversion. The repository's small API server is not evidence of a production-ready multi-tenant queue. Marker was not executed in our historical comparison, so this guide makes no measured quality, memory, or latency claim for it.

pdfplumber: extraction primitives, not a built-in OCR pipeline

pdfplumber is useful for machine-generated PDFs, detailed PDF objects, customizable extraction, and visual debugging. Its CLI exports text, CSV, or JSON; a Markdown table renderer is additional work. The project documents no OCR and limited support for extracting tables from OCR-derived documents. Official README.

A local-file workflow can use it without a hosted conversion API. That does not replace a network audit of the larger application in which you embed it.

What the historical outputs actually showed

The October 6 experiment used Python 3.11.14, MarkItDown 0.1.8, PyMuPDF4LLM 1.28.2, and pdfplumber 0.11.10. MarkItDown had plugins disabled; pdfplumber was tested with extract_text(), not every table API. The eight generated English fixtures cover prose, columns, simple and special-header tables, scans, mixed pages, and linear formulas.

The following observations are useful evaluation cases, not a current product ranking:

Historical case Observed result Add this to your evaluation
Single-column prose Both Markdown converters retained the expected sentences and paragraph anchors A readable baseline with known source text
Two-column prose MarkItDown and the raw-text baseline interleaved columns; PyMuPDF4LLM preserved the tested sequence Whole-sentence checks across columns
Grouped and rotated headers Row strings survived while local header checks failed Parent/leaf labels, character direction, and actual data-row positions
Mixed text and scan The local calls found 2 of 3 page anchors and no scan sentence A required sentence from every scanned attachment
Linear formulas Expression-match scores differed even when ordinary prose was readable Formula-specific checks against the source

A grouped table can pass a row check and still be ambiguous

The historical PyMuPDF4LLM output was:

|**Item**|**Qty**|**Price**||
        |---|---|---|---|
        |||**Unit**|**Total**|
        |Consulting hours|12|85.00|1020.00|
        |Data export fee|3|40.00|120.00|
        |Template license|1|190.00|190.00|
        

The parent heading and leaf labels occupy different rows. A parser taking the first Markdown row as the entire schema would mislabel the numeric columns. Raw grouped-header output.

The rotated MarkItDown fixture also retained reversed labels such as ecirP tinU outside the table. Keeping the amount strings did not preserve the relationship between each amount and its heading. Raw rotated-header output.

Do not generalize a GitHub issue into a failure rate. A report can help you identify a test case, but verifying a fix requires the reported input and relevant version. Our synthetic samples are not reproductions of every linked issue in a project's tracker.

A hosted service is a separate deployment choice

If operating OCR infrastructure is outside your scope and your document policy permits remote processing, a hosted API is another option. It belongs in a deployment decision, not in a list pretending every product is a local open-source repository.

Markovo is the service we build. Its historical October 6 jobs recovered the scan text and all three mixed-page anchors, while returning invoice tables as HTML. On the linear-formula fixture, normalized expression recall was 0.5, compared with 1.0 for MarkItDown and pdfplumber and 0.75 for PyMuPDF4LLM. Its output included damaged superscript notation such as a^{\wedge}2, so scan recovery did not establish formula fidelity.

These API results are cached and reused in related articles. They are not new live tests, and their zero-duration cache entries are not latency measurements. The service's self-reported quality metadata does not replace source review. Cached API provenance, equation response.

For a hosted integration, read the API documentation and the bounded upload-and-poll example. For an offline requirement, keep evaluating a genuinely local stack rather than assuming that installing a CLI makes a remote service local.

Run a deployment evaluation you can reproduce

Before committing to a project:

  1. Pin the package version or commit, Python version, operating system, OCR engine, and model identifiers.
  2. Save code and model license references for that exact configuration.
  3. Build a small corpus representative of your documents, including failure-prone pages rather than only clean demos.
  4. Save raw output and compare page coverage, reading order, table semantics, formulas, and assets separately.
  5. Measure cold start, normal processing, memory, disk use, and concurrency in your deployment environment.
  6. Verify the network behavior and data-retention requirements of the entire configured pipeline.
  7. Test invalid files, timeouts, worker crashes, and retry behavior before exposing an upload endpoint.
  8. Re-run the acceptance set when changing a converter, model, OCR setting, or major dependency.

Keep maintenance evidence dated. Review releases, relevant issues, tests, and dependency/security notices directly when you make the decision. This guide does not invent current star counts, response-time estimates, or maintenance scores from repository popularity.

The full historical scores and execution records retain all eight fixtures. Their sentence and table scores are string checks; table scores do not prove merged-cell semantics, and formula scores do not prove mathematical equivalence. No downstream LLM answer-quality evaluation was performed.

Choose the simplest deployment that passes your content checks and fits your licensing and data-handling requirements. Then keep that acceptance set beside the integration, so an upgrade is an observable change rather than an assumption.

Sources

  1. microsoft/markitdown
  2. pymupdf/pymupdf4llm
  3. pymupdf/PyMuPDF
  4. datalab-to/marker
  5. jsvine/pdfplumber
  6. 1.28.2-generation documentation
  7. MIT
  8. AGPL-3.0 repository license
  9. Apache-2.0 code license
  10. MIT
  11. license explanation
  12. model license
  13. Official README
  14. installation and OCR dependencies
  15. Official README
  16. Official README
  17. Raw grouped-header output
  18. Raw rotated-header output
  19. Cached API provenance
  20. equation response
  21. full historical scores
  22. execution records