EVEMISSTechnology

Repository guide · overview · v2

microsoft / markitdown

“Python tool for converting files and office documents to Markdown.” — as described by its authors

  • Data Processing
  • Python
  • MIT · open-source license
Original repository
microsoft/markitdown
Source platform
GitHub
Repository owner / organization
microsoft
License
MIT · open-source license
Analyzed revision
ed178952a6672abdfd35b5f9e76a80b6cefc086e
Last verified

Source checked 2026-11-15: default branch still at the analyzed revision.

microsoft/markitdown repository overview

Terms used on this page
Entrypoint record
A file the analyzer marks as a place where execution can start. When it carries a __main__ guard excerpt, the file contains an if __name__ == "__main__": block and the excerpt shows what that block calls; without an excerpt, the file was flagged by its name only.
Bounded static execution path
A call chain reconstructed from the source code without running it, stopped after a fixed number of steps. It shows how far the code can be followed on paper, not what happens at run time.
Unresolved boundary
Where a static path stops because the next call goes into an external library or cannot be resolved without running the code. It marks the edge of this analysis, not a defect in the repository.
Static relations
Calls and imports found in the source. "External or unresolved" relations point outside the analyzed files.
Module role
The analyzer's label for a file, inferred from how many calls go in and out (for example core, entry/orchestration, leaf). It describes a position in the call graph, not the authors' design.
Test-like files
Files whose names or locations look like tests. This analysis counts them; it does not run them.
Observed · inferred · author-claimed · unresolved
How each statement is supported: read directly from the analyzed files; derived by the analyzer from them; stated by the repository's authors (metadata, README); or not established by this analysis.
Verified
Two uses on these pages. In an analyzer record ("verified provenance", "a verified entrypoint") it means the record was read directly from the analyzed files, which these guides call observed; for an entrypoint, the __main__ guard text is present. Since the analyzer fix of 2026-10-04, a file that only has an entrypoint-like name such as cli.py or main.py is recorded as inferred; guides analyzed before that still call such a file verified, and it is still only a guess about how the file is used. It does not mean the code was run or tested. "Last verified" is the date the guide last passed the lab's checks against the analysis record of the stated revision; it is not a review of the repository itself.

A Python monorepo whose GitHub description says it converts files and office documents to Markdown. It holds four packages: a core `markitdown` library, an MCP server, an OCR add-on and a sample plugin. Static call degree points to `_markitdown.py` as the core hub. Most relations are unresolved, and runtime behavior is not established.

What it is

According to its GitHub description, this is a Python tool for converting files and office documents to Markdown. Platform metadata lists Python as the primary language and MIT as the license. The listed topics include markdown, pdf, microsoft-office, openai, langchain and autogen.

Structurally, the repository is a small monorepo. Four pyproject.toml manifests sit under packages/, one each for markitdown, markitdown-mcp, markitdown-ocr and markitdown-sample-plugin.

The latest platform release is v0.1.9. Both markitdown-mcp and markitdown-ocr declare a runtime dependency on markitdown in the range >=0.1.9,<0.2.0.

Judging from the package names and entrypoints, markitdown appears to be the core converter library. The other three packages look like an MCP server wrapper, an OCR add-on and a plugin example.

How it starts

Two __main__ guards sit in library source rather than in tests: packages/markitdown/src/markitdown/__main__.py and packages/markitdown-mcp/src/markitdown_mcp/__main__.py. Both guards call a main() function.

Most other detected guards are in test modules and fixture generators. They hand their own file to pytest.main or call test helpers or a local main directly. Some guards in test_cli_vectors.py and test_module_vectors.py only switch imports.

The bounded static paths in this packet cover only the MCP entry. There, the guard calls main, which builds an argparse parser. The traced paths stop at external boundaries such as argparse.ArgumentParser and parser.add_argument.

At module level the same file references MCPServer and logging.getLogger, and both are left unresolved. For MCPServer, static analysis leaves its origin unresolved; it probably comes from the mcp dependency.

The packet contains no execution path for the core markitdown/__main__.py. How the command-line entry reaches the MarkItDown class is therefore not established here.

Structure

The analyzer's summary places 181 of the 197 files under packages/. The rest are in the root (10), .github (5) and .devcontainer (1).

Ranking modules by resolved cross-module call degree gives a rough picture of the core library:

  • markitdown/_markitdown.py has the most outgoing calls (33, with 4 incoming). It defines the large MarkItDown class (lines 141-861), a ConverterRegistration class and _load_plugins, so it is the likely orchestration hub.
  • _base_converter.py (21 incoming), converters/__init__.py (20), _exceptions.py (19) and _stream_info.py (14) have no outgoing calls. They look like shared definitions, such as DocumentConverter, DocumentConverterResult, StreamInfo and the exception types.
  • converter_utils/docx/math/omml.py (25 outgoing) and latex_dict.py (25 incoming) appear to form a pair that translates Office math markup to LaTeX through oMath2Latex.
  • Format converters such as _xlsx_converter.py and _pptx_converter.py show zero resolved incoming calls. This fits converters being registered and dispatched indirectly rather than called by name.

Dependencies and tests

Dependency records come from the four pyproject.toml files:

  • markitdown: recorded runtime deps include beautifulsoup4, requests, certifi, markdownify, magika, charset-normalizer and defusedxml. Optional deps cover specific formats and services, including python-pptx, mammoth, pandas, openpyxl, xlrd, lxml, pdfminer.six, pdfplumber, olefile, pydub, SpeechRecognition, youtube-transcript-api and Azure packages.
  • markitdown-mcp: mcp (>=2.1.1,<3.0.0) and markitdown.
  • markitdown-ocr: markitdown plus PDF, Office and imaging libraries, with optional openai.
  • markitdown-sample-plugin: markitdown and striprtf.

Several optional records repeat the same name and line, and the packet does not explain why. Only some manifest types are parsed, and versions are recorded as written.

The analyzer counts 112 test or test-like files. The sampled list includes fixture documents, so not all of them are test code. Per-format test modules (CSV, DOCX, EPUB, HTML, PDF, PPTX, XLSX, ZIP and others) each contain a pytest.main guard.

What to read first

This suggested order combines the files the analyzer marked important with the most connected modules:

  1. README.md and LICENSE, both flagged as project-level important files.
  2. packages/markitdown/src/markitdown/__main__.py, then _markitdown.py, focusing on MarkItDown, ConverterRegistration and _load_plugins.
  3. _base_converter.py, _stream_info.py and _exceptions.py for the shared types that converters build on.
  4. One concrete converter, for example converters/_html_converter.py (HtmlConverter), which has both incoming and outgoing calls.
  5. packages/markitdown-mcp/src/markitdown_mcp/__main__.py with tests/test_stdio_protocols.py. Then read packages/markitdown-sample-plugin/tests/test_sample_plugin.py to see how a plugin is exercised.

Limits of this analysis

Of 6,816 static relations, 5,812 are external or unresolved and only 1,004 resolve locally. Most call targets are kept as text rather than linked to code.

The analysis is static only, so dynamic imports, runtime registration and dynamic dispatch are not resolved. The core includes _load_plugins, and the OCR and sample packages appear to be plugins. Which converters are active at runtime therefore cannot be established here.

Install, build and run inference is partial, and no command was verified. For that reason this asset gives no installation or run instructions.

The analyzer's own teaching notes are inconsistent. One says no bounded execution path exists, yet the packet contains several. Another names a test file as the starting point.

Under the analyzer's bounds, files over 400 kB, minified bundles and vendored directories are inventoried but not parsed.

Whether any entrypoint actually runs, and what output it produces, is not established.

What this analysis could not establish

The writing model's own notes on the analysis record. Identifiers such as lim_3, exec_* or claim_… name records of that analysis; the claims table cites the same records.

  • One of the analyzer's teaching claims states that no bounded static execution path is available, but the packet contains execution-path records and the analyzer reports 155 bounded execution paths.
  • The analyzer names different starting points: its repository summary points to the MCP __main__.py, while one of its teaching claims points to a test file (test_cli_vectors.py).
  • The control flow of packages/markitdown/src/markitdown/__main__.py is not covered by any execution path in the packet.
  • Names of the optional-dependency extras in packages/markitdown/pyproject.toml are not in the packet, and several records are duplicated.
  • How markitdown-ocr and markitdown-sample-plugin are discovered and registered at runtime is not established; only file names and import relations hint at a plugin mechanism.
  • The certifi constraint (>=2026.10.19) and other version strings are recorded as written and were not checked.
Claims and evidence — 36 claims, 36 supported by an independent verifier

Every statement above is a claim that cites grounding IDs from the analysis. IDs are internal to the analysis run; the columns show what each claim rests on and how strong that ground is.

Every substantive statement above is a claim bound to grounding IDs of the analyzed revision. Global grounding IDs are namespaced by the analysis run.

Claim Epistemic status Verifier Grounding (global IDs)
c1 The GitHub description says the project is a Python tool for converting files and office documents to Markdown. author_claimed supported analysis_5d9c9ae9a129bff5:meta_description
c2 Platform metadata lists Python as the primary language and MIT as the license, with topics including markdown, pdf, microsoft-office, openai, langchain and autogen. observed supported analysis_5d9c9ae9a129bff5:meta_primary_language, analysis_5d9c9ae9a129bff5:meta_license, analysis_5d9c9ae9a129bff5:meta_topics
c3 The repository has four pyproject.toml manifests under packages/, for markitdown, markitdown-mcp, markitdown-ocr and markitdown-sample-plugin. observed supported analysis_5d9c9ae9a129bff5:ev_manifest_1, analysis_5d9c9ae9a129bff5:dep_1, analysis_5d9c9ae9a129bff5:dep_3, analysis_5d9c9ae9a129bff5:dep_14, analysis_5d9c9ae9a129bff5:dep_16
c4 The latest platform release is v0.1.9, and markitdown-mcp and markitdown-ocr both require markitdown >=0.1.9,<0.2.0 at runtime. observed supported analysis_5d9c9ae9a129bff5:meta_latest_release, analysis_5d9c9ae9a129bff5:dep_2, analysis_5d9c9ae9a129bff5:dep_3
c5 From package names and entrypoints, markitdown appears to be the core converter library, while the other packages look like an MCP server wrapper, an OCR add-on and a plugin example. inferred supported analysis_5d9c9ae9a129bff5:important_6, analysis_5d9c9ae9a129bff5:important_3, analysis_5d9c9ae9a129bff5:important_5, analysis_5d9c9ae9a129bff5:dep_3
c6 Non-test __main__ guards exist in packages/markitdown/src/markitdown/__main__.py and packages/markitdown-mcp/src/markitdown_mcp/__main__.py, and both call main(). observed supported analysis_5d9c9ae9a129bff5:py_entry_d19b256901ab, analysis_5d9c9ae9a129bff5:py_entry_2f852a8015d4
c7 Most other detected __main__ guards are in test modules and fixture generators and call pytest.main on their own file, test helpers or a local main; some guards in test_cli_vectors.py and test_module_vectors.py only switch imports. observed supported analysis_5d9c9ae9a129bff5:py_entry_f44307e3b0be, analysis_5d9c9ae9a129bff5:py_entry_a63fdf323f3b, analysis_5d9c9ae9a129bff5:py_entry_157267349a98, analysis_5d9c9ae9a129bff5:py_entry_007b88c947c9, analysis_5d9c9ae9a129bff5:py_entry_791d98438517
c8 Static paths from the MCP entry go from the guard to main, which reaches argparse.ArgumentParser and parser.add_argument, where the paths stop at unresolved boundaries. inferred supported analysis_5d9c9ae9a129bff5:exec_11e5ff5e359f, analysis_5d9c9ae9a129bff5:exec_51ee1388edd7
c9 The MCP __main__ module references MCPServer and logging.getLogger as unresolved external targets, so the server object probably comes from the mcp dependency. inferred supported analysis_5d9c9ae9a129bff5:exec_b68e1f5a7c8a, analysis_5d9c9ae9a129bff5:exec_67998e701fae, analysis_5d9c9ae9a129bff5:dep_1
c10 No execution path for packages/markitdown/src/markitdown/__main__.py is in the packet, so how it reaches the MarkItDown class is not established. unresolved supported analysis_5d9c9ae9a129bff5:py_entry_d19b256901ab, analysis_5d9c9ae9a129bff5:py_class_54565613c36d
c11 The analyzer summary reports 197 files, 181 of them under packages/, with 10 at the root, 5 in .github and 1 in .devcontainer. inferred supported analysis_5d9c9ae9a129bff5:summary_repository
c12 By static cross-module call degree, _markitdown.py (33 outgoing, 4 incoming) is the likely hub; it defines MarkItDown (lines 141-861), ConverterRegistration and _load_plugins. inferred supported analysis_5d9c9ae9a129bff5:role_13, analysis_5d9c9ae9a129bff5:py_class_54565613c36d, analysis_5d9c9ae9a129bff5:py_class_a5c27a19fe56, analysis_5d9c9ae9a129bff5:py_func_575e8ec2d882
c13 _base_converter.py, converters/__init__.py, _exceptions.py and _stream_info.py have many incoming and no outgoing resolved calls, and look like shared definitions such as DocumentConverter, DocumentConverterResult, StreamInfo and exception types. inferred supported analysis_5d9c9ae9a129bff5:role_11, analysis_5d9c9ae9a129bff5:role_22, analysis_5d9c9ae9a129bff5:role_12, analysis_5d9c9ae9a129bff5:role_14, analysis_5d9c9ae9a129bff5:py_class_b1900e6bc249, analysis_5d9c9ae9a129bff5:py_class_870f0e7b97a3, analysis_5d9c9ae9a129bff5:py_class_90b74f2e9504, analysis_5d9c9ae9a129bff5:py_class_1e5fe54ba53d
c14 omml.py (25 outgoing) and latex_dict.py (25 incoming) appear to form a pair that converts Office math markup to LaTeX via the oMath2Latex class. inferred supported analysis_5d9c9ae9a129bff5:role_20, analysis_5d9c9ae9a129bff5:role_19, analysis_5d9c9ae9a129bff5:py_class_54034cf76a50
c15 _xlsx_converter.py and _pptx_converter.py have zero resolved incoming calls, which is consistent with converters being registered and dispatched indirectly. inferred supported analysis_5d9c9ae9a129bff5:role_43, analysis_5d9c9ae9a129bff5:role_39, analysis_5d9c9ae9a129bff5:py_class_b026ac93be11, analysis_5d9c9ae9a129bff5:py_class_164537a7db47
c16 Dependency records come from four pyproject.toml manifests; markitdown's recorded runtime deps include beautifulsoup4, requests, certifi, markdownify, magika, charset-normalizer and defusedxml. observed supported analysis_5d9c9ae9a129bff5:ev_manifest_1, analysis_5d9c9ae9a129bff5:dep_16, analysis_5d9c9ae9a129bff5:dep_17, analysis_5d9c9ae9a129bff5:dep_18, analysis_5d9c9ae9a129bff5:dep_19, analysis_5d9c9ae9a129bff5:dep_20, analysis_5d9c9ae9a129bff5:dep_21, analysis_5d9c9ae9a129bff5:dep_22
c17 markitdown's optional deps include python-pptx, mammoth, pandas, openpyxl, xlrd, lxml, pdfminer.six, pdfplumber, olefile, pydub, SpeechRecognition, youtube-transcript-api and Azure packages. observed supported analysis_5d9c9ae9a129bff5:dep_23, analysis_5d9c9ae9a129bff5:dep_24, analysis_5d9c9ae9a129bff5:dep_25, analysis_5d9c9ae9a129bff5:dep_26, analysis_5d9c9ae9a129bff5:dep_27, analysis_5d9c9ae9a129bff5:dep_28, analysis_5d9c9ae9a129bff5:dep_29, analysis_5d9c9ae9a129bff5:dep_30, analysis_5d9c9ae9a129bff5:dep_31, analysis_5d9c9ae9a129bff5:dep_32, analysis_5d9c9ae9a129bff5:dep_33, analysis_5d9c9ae9a129bff5:dep_34, analysis_5d9c9ae9a129bff5:dep_35, analysis_5d9c9ae9a129bff5:dep_36, analysis_5d9c9ae9a129bff5:dep_37
c18 markitdown-mcp depends on mcp >=2.1.1,<3.0.0 and on markitdown. observed supported analysis_5d9c9ae9a129bff5:dep_1, analysis_5d9c9ae9a129bff5:dep_2
c19 markitdown-ocr depends on markitdown, pdfminer.six, pdfplumber, PyMuPDF, mammoth, python-docx, python-pptx, pandas, openpyxl and Pillow, with openai as an optional dependency. observed supported analysis_5d9c9ae9a129bff5:dep_3, analysis_5d9c9ae9a129bff5:dep_4, analysis_5d9c9ae9a129bff5:dep_5, analysis_5d9c9ae9a129bff5:dep_6, analysis_5d9c9ae9a129bff5:dep_7, analysis_5d9c9ae9a129bff5:dep_8, analysis_5d9c9ae9a129bff5:dep_9, analysis_5d9c9ae9a129bff5:dep_10, analysis_5d9c9ae9a129bff5:dep_11, analysis_5d9c9ae9a129bff5:dep_12, analysis_5d9c9ae9a129bff5:dep_13
c20 markitdown-sample-plugin depends on markitdown >=0.1.0a1 and striprtf. observed supported analysis_5d9c9ae9a129bff5:dep_14, analysis_5d9c9ae9a129bff5:dep_15
c21 Several optional records repeat the same name and line (e.g. python-pptx at line 39, azure-identity at line 53); the packet does not explain why. inferred supported analysis_5d9c9ae9a129bff5:dep_23, analysis_5d9c9ae9a129bff5:dep_38, analysis_5d9c9ae9a129bff5:dep_52, analysis_5d9c9ae9a129bff5:dep_54
c22 Only requirements files, package.json and pyproject.toml are parsed for dependencies; setup.py, setup.cfg, Pipfile and lock files are not, and versions are recorded as written. observed supported analysis_5d9c9ae9a129bff5:lim_3a
c23 The analyzer counts 112 test or test-like files; the sampled list includes fixture documents, so not all are test code. inferred supported analysis_5d9c9ae9a129bff5:ev_tests_1
c24 Per-format test modules for CSV, DOCX, EPUB, HTML, PDF, PPTX, XLSX and ZIP each contain a __main__ guard that calls pytest.main. observed supported analysis_5d9c9ae9a129bff5:py_entry_6da5faf654d3, analysis_5d9c9ae9a129bff5:py_entry_e1644548438f, analysis_5d9c9ae9a129bff5:py_entry_fd2581a2a85a, analysis_5d9c9ae9a129bff5:py_entry_c1e9a0696ede, analysis_5d9c9ae9a129bff5:py_entry_d48046c8aa24, analysis_5d9c9ae9a129bff5:py_entry_f19b18e9138b, analysis_5d9c9ae9a129bff5:py_entry_fc521ad126e1, analysis_5d9c9ae9a129bff5:py_entry_98eaed3ae984
c25 README.md and LICENSE are flagged by the analyzer as project-level important files. observed supported analysis_5d9c9ae9a129bff5:important_1, analysis_5d9c9ae9a129bff5:important_2
c26 A suggested reading order combines important files with connected modules: start at packages/markitdown/src/markitdown/__main__.py, then _markitdown.py with MarkItDown, ConverterRegistration and _load_plugins. inferred supported analysis_5d9c9ae9a129bff5:important_6, analysis_5d9c9ae9a129bff5:role_13, analysis_5d9c9ae9a129bff5:py_class_54565613c36d, analysis_5d9c9ae9a129bff5:py_class_a5c27a19fe56, analysis_5d9c9ae9a129bff5:py_func_575e8ec2d882
c27 Reading _base_converter.py, _stream_info.py and _exceptions.py next is suggested, because they hold shared types that many modules call into. inferred supported analysis_5d9c9ae9a129bff5:role_11, analysis_5d9c9ae9a129bff5:role_14, analysis_5d9c9ae9a129bff5:role_12, analysis_5d9c9ae9a129bff5:py_class_b1900e6bc249
c28 converters/_html_converter.py (HtmlConverter) has both incoming (6) and outgoing (4) calls, which makes it a reasonable concrete converter to read. inferred supported analysis_5d9c9ae9a129bff5:role_31, analysis_5d9c9ae9a129bff5:py_class_048314abbf0a
c29 The MCP entry, its test_stdio_protocols.py test and the sample plugin test are flagged as likely entrypoints and are suggested for reading after the core. inferred supported analysis_5d9c9ae9a129bff5:important_3, analysis_5d9c9ae9a129bff5:important_4, analysis_5d9c9ae9a129bff5:important_5
c30 Of 6816 static relations, 5812 are external or unresolved and 1004 resolve locally. observed supported analysis_5d9c9ae9a129bff5:relation_counts
c31 Analysis is static only, and the core has a _load_plugins function, so which converters and plugins are active at runtime cannot be established. inferred supported analysis_5d9c9ae9a129bff5:lim_1, analysis_5d9c9ae9a129bff5:py_func_575e8ec2d882, analysis_5d9c9ae9a129bff5:important_5
c32 Install, run and build inference is partial and installation commands are not verified, so this asset gives no install or run instructions. observed supported analysis_5d9c9ae9a129bff5:lim_2
c33 The analyzer's teaching notes conflict with the packet: one says no bounded execution path exists although paths are present, and another names test_cli_vectors.py as the starting point. inferred supported analysis_5d9c9ae9a129bff5:claim_4d30ade3e21e, analysis_5d9c9ae9a129bff5:claim_34d2322830c1, analysis_5d9c9ae9a129bff5:exec_11e5ff5e359f
c34 Files over 400 kB, minified bundles and vendored directories are inventoried but not parsed under the analyzer's bounds. observed supported analysis_5d9c9ae9a129bff5:lim_6
c35 Dynamic dispatch, reflection and runtime framework behavior are outside what static analysis can establish here. inferred supported analysis_5d9c9ae9a129bff5:claim_7c9925f9c8f4, analysis_5d9c9ae9a129bff5:lim_1
c36 Whether any entrypoint actually runs, and what output it produces, is not established by this analysis. unresolved supported analysis_5d9c9ae9a129bff5:lim_2, analysis_5d9c9ae9a129bff5:claim_7c9925f9c8f4

Sources, rights and disclosure · attribution-license-templates/v0.1

Rights notice. Original repository hosted on GitHub. Repository source code, documentation, names, media, and related project materials remain subject to the rights of their respective authors, contributors, and other rights holders and to applicable repository license terms.

Platform notice. GitHub is the source hosting platform for the linked repository. GitHub and related marks are trademarks of GitHub, Inc. EVEMISS Technology is not affiliated with or endorsed by GitHub unless explicitly stated otherwise.

How this page is produced. This page was produced using revision-aware repository analysis and AI-assisted editorial tooling. Technical claims are tied to the analyzed repository revision and may be revalidated when the source repository changes.

AI-assisted analysis. Reviewed by EVEMISS Technology through human–AI collaborative review. · Report a rights concern · All repository guides